Micro-project : 01—Discover the Application of the Micro-Project, Minisocs
Understand and test all the artefacts provided at the beginning of
the micro-project.
Getting started
Connect to the GitLabEnse platform at https://gitlabensee.imtbs-tsp.eu by using the button SSO IMTBS-TSP SSO.
Select button Explore project at the top right of the page and search for project csc-mw-project.
In the csc-mw-project page, select the Fork button at the top right of the page. Please, do not change the name of the project: we use scripts to parse your projects.
To add a collaborator to your project, they must log in to the platform at least once. Next, in the left-hand menu, select Manage /Members; then, in the top-right corner of the page, click Invite Members; in the pop-up window, search for your collaborator by entering their name and select Owner as their role.
(Mandatory) Add your lecturers to the project members with the Maintainer role (so that we could help you in the management of the Git repository).
(Mandatory) Use the email on push feature to track the progress of your project. Once on your project page, in the left-hand menu, select Settings / Integrations to access the Emails on push page. In this page, select Send from committer and enter the email addresses of the project members, including those of the theachers.
In a console, execute the following:
-
Clone the Git repository of the GitLabEnse project, the
address being visible with blue-colored button Code
(choose the Clone with SSH address):
$ cd $ mkdir CSC5002 $ git clone git@gitlabensee.imtbs-tsp.eu:csc5002-teachers/csc-mw-project.git $ cd csc-mw-project $ ls -1 MiniSocs # Directory containing the code (you can make backup copy) readme.md # Documentation for getting started + status of the project $ ls -1 MiniSocs/ anomaly-detection # Microservice Anomaly Detection: to be ignored at the beginning LICENSE.txt # minisocs-frontend # Microservice MiniSocs Frontend: to develop first pom.xml # POM for configuring Maven properties that are common to all the other Maven modules readme.md # $ ls -1 MiniSocs/minisocs-frontend/ common-api # Maven module of the API of the application Diagrams # PlantUML diagrams of the documentation hexagon # Maven module of the business part of the application LICENSE.txt # pom.xml # POM for the MiniSocs Frontend microservice readme.md # MarkDown file with the documentation of the MiniSocs application
-
Compile and install the code:
$ cd MiniSocs/ $ mvn clean install # the first compilation takes some time [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Build Order: [INFO] ... [INFO] MINI SOCial networkS [pom] [INFO] MINI SOCial networkS: the common part with the API [jar] [INFO] MINI SOCial networkS: the hexagon or business logic [jar] ... [INFO] ----------------------< minisocs:minisocs-frontend >---------------------- ... [INFO] ------------------------------------------------------- [INFO] T E S T S [INFO] ------------------------------------------------------- ... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary for MINI SOCial networkS 1.0-SNAPSHOT: [INFO] [INFO] MINI SOCial networkS ............................... SUCCESS [ 0.891 s] [INFO] MINI SOCial networkS: the common part with the API . SUCCESS [ 2.175 s] [INFO] MINI SOCial networkS: the hexagon or business logic SUCCESS [ 4.520 s] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: x.xxx s [INFO] Finished at: xxx-xx-xxTxx:xx:xx+xx:xx [INFO] ------------------------------------------------------------------------
- Import the Maven projects in the Eclipse IDE: Select IDE menu File / import; then select Maven / Existing Maven Projects, and use the Browse button to select directory csc-mw-project/MiniSocs. You can see the seven Maven projects in your IDE, three for the Anamoly Detection microservice (namely, minisocs-anomaly-dection, minisocs-anomaly-detection.common-api, and minisocs-anomaly-detection.hexagon), three for the MiniSocs Frontend microservice (namely, minisocs-frontend, minisocs-frontend.common-api, and minisocs-frontend.hexagon), and one for configuring Maven, whose name is minisocs-BOM (BOM stands for Bill Of Materials).
-
In Eclipse, execute JUnit test
class TestScenario: Browse the classes of
the minisocs-frontend.hexagon Maven project to
find the class; then, right-click on the class and select
menu Run As / JUnit Test. You should see in
the Eclipse console some text similar to the following:
moderator, new notification : type = new message; contents = {"newMessages":[{"nameSocialNetwork":"csc5002","instant":1787666233.363248481,"content":"messageModerator"}]} member, new notification : type = new message; contents = {"newMessages":[{"nameSocialNetwork":"csc5002","instant":1787666233.363248481,"content":"messageModerator"}]} moderator, new notification : type = moderation request; contents = {"nameSocialNetwork":"csc5002","instant":1787666233.588221699} ... otherMember, new notification : type = new messages; contents = {"newMessages":[{"nameSocialNetwork":"csc5002","instant":1787666233.809337644,"content":"otherMessageModerator"},{"nameSocialNetwork":"csc5002","instant":1787666233.588221699,"content":"messageMember"},{"nameSocialNetwork":"csc5002","instant":1787666233.363248481,"content":"messageModerator"}]}
-
In a terminal, in
directory MiniSocs-solution/minisocs-frontend/hexagon/,
execute the same JUnit test class with the following Maven
command:
$ mvn test -Dtest=mw.minisocs.validation.TestScenario
Organisation of the code
We use Maven for organising the code and building the software.
Verify that you are able to answer the following questions on Maven.
How many Maven projects exist? What are their names?
Currently, the MiniSocs Frontend microservice is decomposed
into three Maven projects:
namely minisocs-frontend,
minisocs-frontend.common-api,
and minisocs-frontend.hexagon.
Build a graph displaying the "parent—child" relationships and
the module dependencies. How do you find "parent—child"
relationships and module dependencies?
The parent—child relationship between modules is introduced
by the following XML code at the beginning of
the pom.xml files:
At the beginning of the pom.xml files, let us
observe that the packaging is of type pom
for parent module minisocs-frontend, and of
type jar for children
modules minisocs-frontend.common-api
and minisocs-frontend.hexagon. The first type
indicates that there is no Java code while the second is for
modules with some Java code.
The module dependencies are declared in files pom.xml with in tags <dependencies> and <dependency>.
The parent module at the root (file pom.xml in directory MiniSocs) is used to centralise the Maven configuration for all the other modules in the system under development: e.g. version of JAVA and other libraries, and Maven plug-ins to use when building the modules with some Java code, etc.
We have placed the API, along with constants and common classes, in the minisocs-frontend.common-api module. The objective is that all the other modules share this code by using a Maven dependency relationship.
<parent>
<groupId>...</groupId>
<artifactId>...</artifactId>
<version>...</version>
</parent>
The module dependencies are declared in files pom.xml with in tags <dependencies> and <dependency>.
The parent module at the root (file pom.xml in directory MiniSocs) is used to centralise the Maven configuration for all the other modules in the system under development: e.g. version of JAVA and other libraries, and Maven plug-ins to use when building the modules with some Java code, etc.
We have placed the API, along with constants and common classes, in the minisocs-frontend.common-api module. The objective is that all the other modules share this code by using a Maven dependency relationship.
Why is the application API placed in a separate module?
The API is in a separate module so that we can build clients
accessing the application in a distributed manner. More
precisely, we are going to build a middleware adapter that is
going to follow external calls from the network to the
application. That adapter should conform to the API.
Requirements, Specification, and Design of the application
The requirements, the specification and the design of the application are documented in file MiniSocs/minisocs-frontend/readme.mdreadme.md. This a MarkDown file that you can visualise and read in your browser: as its name suggests, this is the main page of the GitLab project.
Please also note that some validation tests are set out in the same readme.md MarkDown documentation file.
Verify that you are able to answer the following questions on the documentation of the application.
(Requirements) What are the main requirements that differ from
popular social networks?
One key difference is that a user joins multiple social
networks, each of which has a small number of members.
Secondly, the main difference and the added value of the application lie in the moderation of each message within a social network; this is possible because there are few members in a social network.
Thirdly, the users can choose to be notified of new messages according to several strategies: immediate, daily, etc.
Secondly, the main difference and the added value of the application lie in the moderation of each message within a social network; this is possible because there are few members in a social network.
Thirdly, the users can choose to be notified of new messages according to several strategies: immediate, daily, etc.
(Specification, use case diagram) Compile the list of use cases
that are implemented and the list of uses cases thar are not
implemented. As a reminder, this a ‘toy’ application for
learning purposes and the system is thus far from complete.
The list of uses cases that are implemented: add user, list
users, deactivate user account, create social network, list
social networks, close social network, add member to social
network, moderate message, list members of a social network,
list moderators of a social network, post message, read latest
messages.
The list of uses cases that are not implemented yet: block user account, remove user account, remove social network, remove member, promote user as moderator, remove moderation for user, modify one of their messages, hide one of their messages, remove one of their messages.
The list of uses cases that are not implemented yet: block user account, remove user account, remove social network, remove member, promote user as moderator, remove moderation for user, modify one of their messages, hide one of their messages, remove one of their messages.
(Specification, pre- and post-conditions) Verify that you can
read the preconditions and the postconditions in
Section 2.2. Establish the input and the output data of
some of the use cases, e.g. a simple use case (add a user), a
more complex one (moderate a message).
The input data of use case ‘add a user‘ are: the user's
pseudo, the user's name, the user's firstname, the user's
email. There is no output provided by the system: the pseudo
will serve as the unique identifier to retreive user data
after the execution of the use case.
The input data of use case "moderate a message" are: the moderator's pseudo, the name of the social network, the instant of creation of the message, the moderator's decision. The first three arguments are unique identifiers of the user, the social network, and the message, respectively.
N.B. : in this ‘toy’ application, it is reasonable to uniquely identify a message with the instant of its creation.
The results of this use case are notifications of the new message sent to members who have selected the ‘immediate’ notification strategy.
The input data of use case "moderate a message" are: the moderator's pseudo, the name of the social network, the instant of creation of the message, the moderator's decision. The first three arguments are unique identifiers of the user, the social network, and the message, respectively.
N.B. : in this ‘toy’ application, it is reasonable to uniquely identify a message with the instant of its creation.
The results of this use case are notifications of the new message sent to members who have selected the ‘immediate’ notification strategy.
(Preparation of the validation tests) Check that you can draw up
the decision tables in Section 3 based on the preconditions and
postconditions in Section 2.2. In particular, what is the
meaning of the last lines ‘number of tests’.
Ask questions in case of difficulties.
(Design, class diagram) What is the role of
the MiniSocs and of
the NotificationManager classes?
MiniSocs is the Façade (Design Pattern Façade),
that is the unique entry point to the system. All the use
cases give rise to a method in the Façade.
NotificationManager plays the same role, but for the exit: This is the unique exit point of the system. All the Java Flow SubmissionPublisher objects are in that class, and all the notifications go through that class.
NotificationManager plays the same role, but for the exit: This is the unique exit point of the system. All the Java Flow SubmissionPublisher objects are in that class, and all the notifications go through that class.
(Design, sequence diagrams) Verify that you can read the
sequence diagrams of Section 4.2. For instance, at the end
of sequence ‘add a member to a social network’, what is the
value of attribute pseudo in the newly created
object of type Participation? If you cannot find
the answer in the diagram, then read the code.
The user's pseudo is used by default as the member's
pseudo. This can be established by reading both the sequence
diagrame and the code.
(Design, state machine diagrams and invariants) Check that the
requirements of deactivating and blocking a user account are
fulfilled in the state machine diagram. What is your opinion
about the many transitions to the ‘InDeletion’ states.
It may not be reasonable to delete users when they have
participations to social networks. The question of what
happens to messages posted by a user who is to be removed from
the system remains an open one.
In the other state machine diagram, similar questions arise regarding the deletion of social networks.
In the other state machine diagram, similar questions arise regarding the deletion of social networks.
Java Code of the Application
Verify that you are able to answer the following questions on the code of the application.
Verify that the code implements all the use cases for which we
have specified ther pre- and post-conditions.
For each of these use cases, there is a corresponding method
in the Façade, i.e. class MiniSocs.
Check that you can trace all the terms of the preconditions in
the code.
Note that the sequence diagrams of Section 4.2 model
complete use cases, i.e. the implementation of a use case for
which we have drawn a sequence diagram can be entirely traced
from its sequence diagram.
Given a use case, the implementation of a sequence diagram is found in part whithin the corresponding method of the Façade, and the sub-messages are found in the methods called by the Façade's method.
Let us observe that these verifications may through exceptions of type UnfeasibleOperation.
Given a use case, the implementation of a sequence diagram is found in part whithin the corresponding method of the Façade, and the sub-messages are found in the methods called by the Façade's method.
Let us observe that these verifications may through exceptions of type UnfeasibleOperation.
Why some terms of the preconditions are checked in the Façade
and also in other methods, e.g. the domain value of an input
parameter such the user's pseudo is tested both in
method addUser and in the constructor of
class User? What types of exceptions are thrown?
The second test in the constructor is called defense
programming. When the condition is false, i.e. there is a
problem, since this is the second time the term is tested, it
is considered a programming error. As a consequence, the
exception that is thrown is an unchecked
or RuntimeException (and its subclasses).
On the contrary, the exceptions thrown by the Façade's methods are part of their prototype (the programming interface). As a consequence, we use checked exceptions.
On the contrary, the exceptions thrown by the Façade's methods are part of their prototype (the programming interface). As a consequence, we use checked exceptions.
Check that you understand the notification mechanism using the
Java Flow API, and more especially, the content and the role of
class NotificationManager.
Ask questions in case of difficulties.
Congratulations, you are now ready to start contributing to the
project for building a distributed version of the application.
