MANUAL DO ALUNO DE ENGENHARIA DE SOFTWARE

Transcription

1 MANUAL DO ALUNO DE ENGENHARIA DE SOFTWARE [Document Subtitle] João Dias Pereira Instituto Superior Técnico ES 2014/15 [ 1 / 50 ]

2 Introduction This document presents the several tools and technologies that the students need to apply during the development of the project of the Software Engineering course. It is composed of two parts. The first part describes the Maven tool, a software project management tool. The second part presents the technologies (Fénix framework and DML language) and the layered architecture to be applied in the development of the project of this course. ES 2014/15 [ 2 / 50 ]

3 ES 2014/15 [ 3 / 50 ]

4 Maven The goal of this Section is to introduce the Maven tool. This document just shows some of the functionalities of Maven. A complete guide about Maven can be found in Maven is a software project management tool. Maven is a Java tool, therefore you need to have Java installed in your machine in order to use this tool. Maven simplifies and standardizes the project build process. It handles compilation, distribution, documentation, team collaboration and other tasks seamlessly. Using Maven means developers are not required to create or specify the build process themselves or to mention each and every configuration detail. Maven provides sensible default behavior for projects. When a Maven project is created, Maven creates a default project structure. Developer is only required to place files accordingly. The information about the project and various configuration details used by Maven to build the project is represented in the Project Object Model (POM). The POM is an XML file that resides in base directory of the project. POM Each Maven project is described by a file named pom.xml stored in the home directory of the project. This file contains the Project Object Model (POM) for the project. The POM is the basic unit of work in Maven. The POM file contains every important piece of information about the project. Understanding the POM is important. The key elements that every POM file contains are the following: project This is the top- level element in all Maven pom.xml files. modelversion This element indicates what version of the object model this POM is using. The version of the model itself changes very infrequently but it is mandatory in order to ensure stability of use if and when the Maven developers deem it necessary to change the model. groupid This element indicates the unique identifier of the organization or group that created the project. The groupid is one of the key identifiers of a project and is typically based on the fully qualified domain name of your organization. For example org.apache.maven.plugins is the designated groupid for all Maven plug- ins. artifactid This is the identifier of the project. This is generally the name of the project. This element indicates the unique base name of the primary artifact being generated by this project. The primary artifact for a project is typically a JAR file. Secondary artifacts like source bundles also use the artifactid as part of their final name. A typical artifact produced by Maven would have the form <artifactid>- <version>.<extension>. ES 2014/15 [ 4 / 50 ]

5 Maven packaging This element indicates the package type to be used by this artifact (e.g. JAR, WAR, EAR, etc.). This not only means if the artifact produced is JAR, WAR, or EAR but can also indicate a specific lifecycle to use as part of the build process. The default value for the packaging element is JAR so you do not have to specify this for most projects. version This element indicates the version of the artifact generated by the project. Maven goes a long way to help you with version management and you will often see the SNAPSHOT designator in a version, which indicates that a project is in a state of development. name This element indicates the display name used for the project. This is often used in Maven's generated documentation. url This element indicates where the project's site can be found. This is often used in Maven's generated documentation. description This element provides a basic description of your project. This is often used in Maven's generated documentation. POM also contains the goals and plugins. While executing a task or goal for a project, Maven looks for the POM in the current directory. It reads the POM, gets the needed configuration information, and then executes the goal. When you start a Maven project, the first thing you need to do is to create it. To create a Maven project you can use the Maven's archetype mechanism. An archetype is defined as an original pattern or model from which all other things of the same kind are made. In Maven, an archetype is a template of a project that is combined with some user input to produce a working Maven project that has been tailored to the user's requirements. Build Lifecycle Basics The current version of Maven is based around the central concept of a build lifecycle. This means that the process applied by Maven for building and distributing a particular artifact (project) is clearly defined. For the person building a project, this means that it is only necessary to learn a small set of commands to build any Maven project, and the POM will ensure they get the results they desired. There are three built- in build lifecycles: default handles the project deployment; clean - handles project cleaning; site - handles the creation of the project's site documentation. A build lifecycle is a well defined sequence of phases that define the order in which the goals are to be executed. Here phase represents a stage in life cycle. ES 2014/15 [ 5 / 50 ]

6 Maven Each build lifecycle is defined by a different list of build phases. A build phase represents a stage in the lifecycle. For example, the default lifecycle has the following build phases: validate - validate the project is correct and all necessary information is available compile - compile the source code of the project test - test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed package - take the compiled code and package it in its distributable format, such as a JAR. integration- test - process and deploy the package if necessary into an environment where integration tests can be run verify - run any checks to verify the package is valid and meets quality criteria install - install the package into the local repository, for use as a dependency in other projects locally deploy - done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects. The build phases of a build lifecycle are executed sequentially to complete the build lifecycle. Considering the build phases above, this means that when the default lifecycle is used, Maven will first validate the project, then will try to compile the sources, run those against the tests, package the binaries (e.g. jar), run integration tests against that package, verify the package, install the verified package to the local repository and then deploy the installed package in a specified environment. To do all those, you only need to call the last build phase to be executed, in this case, deploy: $> mvn deploy That is because if you call a build phase, it will execute not only that build phase, but also every build phase prior to the called build phase. Thus, doing $> mvn integration- test will do every build phase before it (validate, compile, package, etc.), before executing integration- test. A goal represents a specific task that contributes to the building and managing of a project. It may be bound to zero or more build phases. A goal not bound to any build phase could be executed outside of the build lifecycle by direct invocation. The order of execution depends on the order in which the goal(s) and the build phase(s) are invoked. Consider the following command: $> mvn clean dependency:copy- dependencies package ES 2014/15 [ 6 / 50 ]

7 Maven In this command, the clean and package arguments are build phases while the dependency:copy- dependencies argument is a goal. The clean phase will be executed first, followed by the execution of the dependency:copy- dependencies goal, and finally the package phase will be executed. Maven Plugins Maven is actually a plugin execution framework where every task is actually done by plugins. A plugin generally provides a set of goals that can be executed using following syntax: $> mvn [plugin- name]:[goal- name] A plugin goal represents a specific task (finer than a build phase) which contributes to the building and managing of a project. It may be bound to zero or more build phases. A goal not bound to any build phase could be executed outside of the build lifecycle by direct invocation. The order of execution of a Maven command depends on the order in which the goal(s) and the build phase(s) are invoked, as we saw before. Moreover, if a goal is bound to one or more build phases, that goal will be called in all those phases. Furthermore, a build phase can also have zero or more goals bound to it. If a build phase has no goals bound to it, that build phase will not execute. But if it has one or more goals bound to it, it will execute all those goals. A build phase is made up of plugin goals. A build phase is responsible for a specific step in the build lifecycle, but the manner in which it carries out those responsibilities may depend on the type of project. The plugin provides a way of customization of the build phases. It is possible to specify a plugin and the define the phase or phases where the plugin should start its processing in the POM of the project. Create a Java Project Maven uses the archetype plugins to create projects. To create a simple java application, we will use maven- archetype- quickstart plugin (there are other archetype plugins for different types of Java projects). In the example below, we are creating a maven based java application project in the current directory: $>mvn archetype:generate -DgroupId=pt.ist.phonebook -DartifactId=phonebook - DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false ES 2014/15 [ 7 / 50 ]

8 Maven When you execute this command in a shell, Maven will start processing and will create a complete java application with the project structure described bellow. If you have just installed Maven, this command may take a while on the first run. This is because Maven is downloading the most recent artifacts (plugin jars and other files) into your local repository. You may also need to execute the command a couple of times before it succeeds. This is because the remote server may time out before your downloads are complete. The first parameter of this command says that Maven is going to apply the archetype plugin. This plugin allows you to create a Maven project from a pre- defined model. Next, we define the goal to apply for this plugin: generate. This goal creates a project from a template. There are more goals available for this archetype. As we saw before, the second parameter, groupid, just defines the organization or the project. The third parameter specifies the name of the project (phonebook in the example). The fourth parameter, archetypeartifactid, defines the model that it will be used for the generation of the new Maven project. The model that we are using in this case is maven- archetype- quickstart. This model should be used when you want to create a simple Java project. Finally, the last parameter, interactivemode, just specifies whether the user will provide extra information during the creation of the project. After the execution of this command, you will notice that the generate goal created a directory with the same name given as the artifactid. This directory will contain all files related to this project. Maven projects have a common directory layout. This allows users familiar with one Maven project to immediately feel at home in another Maven project. The generated Maven project created before has this standard project structure: phonebook -- pom.xml `-- src -- main `-- java `-- pt `-- ist `-- phonebook `-- App.java `-- test `-- java `-- pt `-- ist `-- phonebook `-- AppTest.java The src directory is the root directory of the project s source code and test code. The main directory is the root directory for source code related to the application itself (not test code). The test directory contains the test source code. The java directories under main and test contains the Java code for the application itself (under main) and the Java code for the tests (under test). You can also have a resources directory under main and test directories. This directory holds other resources needed by your project, for instance, property files used for internationalization of the application. ES 2014/15 [ 8 / 50 ]

9 Maven Is the Maven project is a web application then the project directory structure will also have the webapp directory. This directory will then be the root directory of the web application. Thus the webapp directory contains the WEB- INF directory, etc. Finally, Maven automatically creates the target directory. This directory contains all the compiled classes, JAR files etc. produced by Maven. When executing the clean build phase, this directory is removed. Compile and Run the Unit Tests Once the application s sources compile without errors, you should test the code using the JUnit tests developed by you. To execute these tests you should execute the following command: $> mvn test Executing this command line causes Maven to execute all lifecycle phases up to the test phase. This phase executes all unit tests of this project it can find under src/test/java with filenames matching **/Test*.java, **/*Test.java and **/*TestCase.java excluding those that match **/Abstract*Test.java or **/Abstract*TestCase.java. The first time you execute this command Maven may download more dependencies. These are the dependencies and plugins necessary for executing the tests. Before compiling and executing the tests, Maven compiles the main code but it only compiles those classes that have been modified since the last time the project was compiled. It is also possible to simply compile the test sources without executing the test. For doing this, execute the following: $>mvn test- compile The Maven Surefire plugin has a test goal that is bound to the test phase. When the Surefire plugin runs the JUnit tests, it also generates XML and text reports in the target/surefire- reports directory. If your tests are failing, you should look in this directory for details like stack traces and error messages generated by your unit tests. To run a single test class (for instance, TestApp1), you can issue the following command: mvn - Dtest=TestApp1 test. ES 2014/15 [ 9 / 50 ]

10 Maven Maven always by default run your unit tests whenever Maven executes a phase that comes after the test phase. Sometimes, however, you want to execute the phase without running the unit tests. You can do so setting the maven.test.skip property to true. Thus, executing the following command: $> mvn install - Dmaven.test.skip=true builds the project but skips the execution of the unit tests. Package a Project Since it s unlikely that a developer will want want to distribute their project with the.class files directly, it is necessary to package the project first. This is accomplished by executing the following command: $> mvn package The package phase takes the compiled code and packages it in its distributable format, such as a JAR, WAR, or EAR file. The distributable format is chosen taking into account the value specified for the packing element present in the pom.xml file of the Maven project. The name of the package file will be based on the project s <artifactid> and <version>. This file is placed in the target directory present in the project s home directory. If a developer wants to install this generated file in the local repository, he just has to execute the following command: $> mvn install Run a Java Class You can run a Java class using the Maven exec plugin using the following command: $>mvn exec:java - Dexec.mainClass="com.example.Main" [- Dexec.args="arguments"] The last parameter of this command, exec.args, is optional and it is needed only if you have to provide arguments to the execution of the Java class. The exec plugin has supports two goals: exec:exec executes programs and Java programs in a separate process. exec:java executes Java programs in the same VM. Another way of executing the main method of a Java class is by customizing the exec plugin in the POM file. For instance ES 2014/15 [ 10 / 50 ]

11 Maven <build> <plugins> <plugin> <groupid>org.codehaus.mojo</groupid> <artifactid>exec- maven- plugin</artifactid> <version>1.1.1</version> <executions> <execution> <phase>test</phase> <goals> <goal>java</goal> </goals> <configuration> <mainclass>com.java2s.ide.app</mainclass> <arguments> <argument>arg0</argument> <argument>arg1</argument> </arguments> </configuration> </execution> </executions> </plugin> </plugins> </build> Clean the Project To remove all files automatically generated during the build project you should execute the following: $> mvn clean This will remove the target directory, which contains all the build data, from the project s home directory. Declare Dependencies The simple Hello World sample that is created when the is usedis completely self- contained and does not depend on any additional libraries. However, most applications depend on external libraries to handle common and complex functionality. These dependencies must be defined in the POM. For example, suppose that in addition to saying "Hello World!", you want the sample application to print the current date and time using the Joda Time libraries. First, you should change HelloWorld.java to look like this: package hello; import org.joda.time.localtime; public class HelloWorld { public static void main(string[] args) { LocalTime currenttime = new LocalTime(); System.out.println("Hello World! The current local time is: " + currenttime); ES 2014/15 [ 11 / 50 ]

12 Maven } } In this example we are using Joda Time s LocalTime class to get and print the current time. Now, if you were to run mvn compile to build the project, the build would fail because you have not declared Joda Time as a compile dependency in the build for this project. You can fix that by adding the following lines to pom.xml (within the <project> element): <dependencies> <dependency> <groupid>joda- time</groupid> <artifactid>joda- time</artifactid> <version>2.2</version> </dependency> </dependencies> This block of XML declares a list of dependencies for the project. Specifically, it declares a single dependency for the Joda Time library. Within the <dependency> element, the dependency coordinates are defined by three sub- elements: <groupid> - The group or organization that the dependency belongs to. <artifactid> - The library that is required. <version> - The specific version of the library that is required. By default, all dependencies are scoped as compile dependencies. That is, they should be available at compile- time (and if you were building a WAR file, including in the /WEB- INF/libsfolder of the WAR). Additionally, you may specify a <scope> element to specify one of the following scopes: provided - Dependencies that are required for compiling the project code, but that will be provided at runtime by a container running the code (e.g., the Java Servlet API). test - Dependencies that are used for compiling and running tests, but not required for building or running the project s runtime code. Now if you run mvn compile or mvn package, Maven should resolve the Joda Time dependency from the Maven Central repository and the build will be successful. Maven Repositories In Maven terminology, a repository is a place i.e. directory where all the project jars, library jar, plugins or any other project specific artifacts are stored and can be used by Maven easily. A repository in Maven is used to hold build artifacts and dependencies of varying types. There are strictly only two types of repositories: local and remote. A Maven local repository is a folder location on your machine. The local repository refers to a copy on your own installation that is a cache of the remote downloads (library jars, plugin jars, etc), and also ES 2014/15 [ 12 / 50 ]

13 Maven contains the temporary build artifacts that you have not yet released. The local repository keeps all dependencies of your Maven projects. The local repository is automatically created when you run any Maven command for the first time. By default, this directory is named repository and it is placed in directory ~/.m2. When you build a Maven s project, Maven will check the project s POM to identify the dependencies of the project. All dependencies that are missing in the local repository are automatically downloaded from a remote repository. First, Maven will get the dependency from the local repository. If the dependency is not found in the local repository, Maven will try to get it from the Maven central repository This central repository is a repository provided by Maven community. It contains a large number of commonly used libraries. To browse the content of central maven repository, maven community has provided the following URL: Using this URL, a developer can search all the available libraries in central repository. Sometime, Maven does not find a mentioned dependency in the central repository as well. When this happens, the build process stops and it prints an output error message in the console. To prevent such situation, Maven allows users to specify other remote repositories that will contain required libraries or other project jars. These extra remote repositories are specified in the project s POM. A dependency is searched in this remote repository if the dependency is not found neither in the local repository nor in the central repository. Eclipse IDE To make a Maven project as an Eclipse project, execute the following command in the project s home directory: $> mvn eclipse:eclipse The execution of this command will generate all project files that are required by Eclipse IDE. To import the project into the Eclipse IDE, select File - > Import - > General- >Existing Projects into Workspace. ES 2014/15 [ 13 / 50 ]

14 Development of Web Applications using the Fénix Framework and Layer Architecture Introduction The goal of this Section is to help students to develop the project of the Software Engineering course. This Section mainly describes the following: The Fénix Framework The DML language The maven project to be used to develop an application in this course that uses the Fénix Framework The layered architecture to be applied in the project Lesson 1: Welcome to the Fénix Framework project Fénix Framework allows the development of Java- based applications that need a transactional and persistent domain model. Even though it was originally created to support the development of web applications, it may be used to develop any other kind of applications that need to keep a persistent set of data. One of the major design goals underlying the development of the Fénix Framework is that it should provide a natural programming model to programmers used to develop plain Java programs without persistence. Often, the addition of persistence, typically backed up by a relational database management system, interferes with the normal coding patterns of object- oriented programming, because the need to access the database efficiently precludes the use of many of the powerful mechanisms available in the object- oriented paradigm. Other frameworks and tools, often called Object- Relational Mapping (O/RM) frameworks, address this problem by giving the programmer ways to specify how objects are mapped into the relational database and by doing most of the heavy lifting needed to access the data in the database. Yet, they fail to completely hide the presence of the database, meaning that the problem remains. With the Fénix Framework, on the other hand, the relational concerns with database are completely hidden from the programmer. This has two consequences: The programmer no longer can control the mapping of objects to the database; ES 2014/15 [ 14 / 50 ]

15 There is no way to take advantage of database facilities, such as joins or aggregate functions. In return, programmers may, and are encouraged to, use all of the normal object- oriented programming coding patterns. Since version 2.x, the Fénix Framework provides several backends to support transactions and the persistency of data. The one we are going to apply in the project for Software Engineering is based on a Software Transactional Memory library and the data is stored in a relational database system. Programmers using the Fénix Framework specify the structure of the application's domain model using a new domain- specific language created for that purpose, the Domain Modeling Language (DML), and then develop the rest of the application in plain Java. No configuration files, XML files, or property files are needed. In a nutshell, to use the Fénix Framework programmers have to do the following: 1. Define the structure of the domain model in DML; 2. Write the rest of the program in plain Java; 3. Use annotation on the methods that should execute atomically; 4. Create an empty database; 5. Build the project and run the application. ES 2014/15 [ 15 / 50 ]

16 Lesson 2: What is this DML thing anyway? In every software application, there is a domain model that describes the entities and their relations that the software application intends to abstract and manipulate. Using the Object- Oriented Programming (OOP) paradigm, programmers may easily specify the domain model of a software application by structuring those entities as classes from which new instances can be created. OO programming languages, like Java, offer a set of constructs (e.g. classes, composition and inheritance) that programmers can use to implement a domain model. However, these general- purpose languages do not provide specific declarative primitive constructs to specify domain models that would help programmers to easily specify the domain model of their applications, such as the storage in a database or the access by multiple concurrent threads in a consistent way. A language, specifically designed for this purpose, is called a Domain Modeling Language (DML). The Fénix Framework includes one of such languages. It provides a persistent and transactional infrastructure that eases the development of Java applications, and it also provides a new language called the Domain Modeling Language (DML) which complements and integrates with the Java programming language. The reason for using this framework is that Java programmers must manually implement all the relations between classes in an ad- hoc manner, which is a time- consuming and error- prone activity. Also, Java does not provide means for creating new syntactic structures to extend Java constructs in order to support these mechanisms. The Fénix Framework automatically translates the DML specification into the necessary classes that fully implement relations as described by the developers, liberating them from the repetitive burden that would encompass the translation of the domain model into Java source code, which would be responsible for actually enforcing and delivering the desired structural relations. Traditionally, to provide the required structural aspects, code conventions are defined. However, these conventions need to be applied manually by the developers and must be consistently used across the entire project to avoid errors. This is especially time- consuming when persistent and transactional behavior is needed. The generated classes, derived from the DML specification, can then be extended through the inheritance mechanism already available in an OO language like Java. The Fénix Framework and its DML do not replace Java. Instead, they integrate with Java providing constructs to better represent a domain model s structure, including its structural aspects like relations and leaving all the rest (like behavior) to Java (and the developer). In fact, a domain model is not completed without its behavior and that is not supported by the DML and needs to be later implemented in Java. This includes business logic and domain restrictions. The DML language is considered a micro- language designed specifically to implement the structure of a domain model. This language has constructs for specifying both entity types and relations between them. Based on the DML specification, a compiler can automatically generate code to be integrated with a regular programming language, such as Java. The DML allows Java programmers to specify the domain model using a syntax that is very similar to Java itself. The DML compiler later reads the set of DML specifications that encode the structure of the domain model and translates it into a set of Java source files. ES 2014/15 [ 16 / 50 ]

17 Lesson 3: The PhoneBook Example Let us imagine that we want to build a simple PhoneBook application, capable of storing a set of contacts for each registered person. A person has a name and each contact is represented by a name and a phone number. Lesson 3.1: Describing the Domain The domain model of the PhoneBook application consists only of three entities: PhoneBook, Person and Contact. The PhoneBook entity represents the class that knows all registered people. Each person maintains his/her own set of contacts. The relationship between these entities is depicted in the following class diagram: 1 * 1 phonebook person person * contact PhoneBook Person Contact Lesson 3.2: Describing entities using the DML Using the DML, we could textually describe the domain model of our PhoneBook application through the following DML code: 1. class PhoneBook; class Person { 4. String name; 5. } class Contact { 8. String name; 9. String phonenumber; 10. } The class of the main object of our PhoneBook application is defined in line 1. Since the PhoneBook class has no fields, we may omit the empty bracket block. On the other hand, when the class to be defined has one or more fields, then the fields must be specified inside a bracket block as exemplified in the definition of the Contact class (lines 7 to 10). The built- in value types (those you can use without declaring them) that the DML supports are: The Java primitive types: boolean, byte, char, short, int, float, long, and double. The wrapper types for the respective Java primitive types: Boolean, Byte, Character, Short, Integer, Float, Long, and Double. These types are typically used when an entity's field is optional, i.e., whether null value is allowed. The String type. The bytearray type (it will map into the Java type byte[]). The Serializable type. To represent dates and their related types, there are the following built- in value- types, from the Joda Time (Java date and time API): DateTime, LocalDate, LocalTime, and Partial. See the documentation for these at time.sourceforge.net/. Finally, the GSON's JsonElement to represent unstructured data. ES 2014/15 [ 17 / 50 ]

18 Lesson 3.3: Describing relations using the DML The DML also allows the programmer to specify the relations between the several entities of the domain model of the application. Usually this is made after the description of the structure of the classes of the domain model since the classes need to be declared (with class ) before they are referred in the specification of the existing relations. Considering the PhoneBook application, now that we have described the structure of each class, we can describe the two bi- directional relations existing in this example. Using the DML, we can easily describe the relation between PhoneBook and Person using the following code: 11. relation PhoneBookContainsPersons { 12. PhoneBook playsrole phonebook; 13. Person playsrole person { 14. multiplicity *; 15. } 16. } In DML, a relation between two classes is specified using the relation construct. By default, all relations in DML are bi- directional. After naming the relation, we have to define the two roles of the participating entities in the bi- directional relation (through the playsrole construct), and their respective cardinality. By default, an empty multiplicity block implies a 0 or 1 multiplicity. This means that line 12 could also be written as: 12. PhoneBook playsrole phonebook { multiplicity 0..1; }; Finally, the whole DML specification describing the domain model of the PhoneBook application must be included in a file (e.g., phonebook.dml) and it should be stored in the specific directory src/main/dml of the Maven project: 1. package pt.tecnico.phonebook.domain; class PhoneBook; class Person { 6. String name; 7. } class Contact { 10. String name; 11. Integer phonenumber; 12. } relation PhoneBookContainsPersons { 15. PhoneBook playsrole phonebook; 16. Person playsrole person { 17. multiplicity *; 18. } 19. } relation PersonContainsContacts { 22. Person playsrole person; 23. Contact playsrole contact { 24. multiplicity *; 25. } 26. } ES 2014/15 [ 18 / 50 ]

19 Note the package definition in line 1. This definition allows the programmer to set the package for all the classes described in the DML specification file. Alternatively, one could provide fully- qualified names for all the specified classes, but in such situations the relations also require the declaration of the fully- qualified name of the classes involved. 1. class pt.ist.phonebook.domain.phonebook; class pt.ist.phonebook.domain.person { 4. String name; 5. } class pt.ist.phonebook.domain.contact { 8. String name; 9. Integer phonenumber; 10. } relation PhoneBookContainsPersons { 13. pt.ist.phonebook.domain.phonebook playsrole phonebook; 14. pt.ist.phonebook.domain.person playsrole person { 15. multiplicity *; 16. } 17. } relation PersonContainsContacts { 20. pt.ist.phonebook.domain.person playsrole person; 21. pt.ist.phonebook.domain.contact playsrole contact { 22. multiplicity *; 23. } 24. } The Fénix Framework compiler will then read our DML file, and automatically generate the classes and the relations described therein. The class that the DML compiler generates (containing only the entity s state) from an entity type specification in DML has both a getter method and a setter method for each of the entity type s fields. The DML compiler generates the names of these methods by concatenating the prefixes get and set, respectively, with the name of the field, after capitalizing the first letter of the attribute. So, given an entity object obj, the method call obj.getattrname() returns the obj s value for the field named attrname, whereas the call obj.setattrname(newval) sets the value of the field to the value newval. No other methods can access the field. In order to separate the domain business logic concerns from the data and its getters and setters, the Fénix Framework generates two different types of classes for each entity specified in the DML file: The base class (also called the state class) is abstract and implements the domain entity s structural aspects. The DML compiler automatically generates this class from the domain specification. Thus, programmers should not edit this class manually. The base class is provided with methods that allow clients of this class to access the fields ES 2014/15 [ 19 / 50 ]

20 and relations of this class specified in the domain model. The behavior class extends the base class and should implement the domain entity s behavioral aspects. The DML compiler cannot automatically generate this class, unlike the state class, because the domain specification does not have any behavior specification. Instead, the implementation of this class is the responsibility of the developers: this is the class where programmers implement the entity s behavior. If this class does not exist yet, the DML compiler automatically generates a file that contains an empty class that represents the behavior class. Even though a state class has all the fields of an entity type and no abstract method, it must be abstract, because it does not represent an entity. An entity contains both state and behavior, but the instances of a state class only contain the state. Therefore, the state class is abstract to prevent the creation of instances of an incomplete custom- made type representing the entity. Using the PhoneBook example, the following class diagram illustrates the inheritance pattern that the Fénix Framework uses in the definition of domain classes. PhoneBook_Base 1 * 1 Person_Base phonebook person person * contact Contact_Base PhoneBook Person Contact Regardless of the multiplicities involved, the methods that implement a relation must allow us to do each one of the following tasks: create a new link between two objects; remove an existing link between two objects traverse from one object in one end of a link to the object on the other end. The specific signature of the methods that allow us to do this depends on the multiplicity of each role. Let us see each case separately : Roles with a multiplicity upper- bound of one If the multiplicity of a role declaration has an upper- bound of one, then an object of the opposite type may refer to at most one object of the role s type. This is the simplest case of a relation, which is typically implemented with a getter and a setter method. ES 2014/15 [ 20 / 50 ]

21 The method setrole is the setter method. It allows us to create or to delete a link between an instance of class B and an instance of class A. The call to the setter method with a null argument eliminates any current link that might exist. The method getrole is the getter method. This method is the method that allows us to traverse the relation. The method hasrole returns true if there is a link between the receiver of the method call and an instance of class A. Otherwise, it returns false. It is equivalent to obj.getrole()!= null. The method removerole removes an existing link that might exist for the receiver of the method call. It is equivalent to call the setter method with a null argument. These last two methods, hasrole and removerole, are no longer generated in the current version of Fénix Framework : Roles with a multiplicity upper- bound greater than one The difference between this case and the previous one is that the object of the opposite type may have multiple links, at the same time, with objects of the role s type. So, when we create a new link, we do not replace any existing link, as in the previous case. The existing links must be removed explicitly, by specifying which object is on the other end of the link that should be removed. Furthermore, when we traverse the relation, we may reach multiple objects. Thus, the getter method must return a collection of objects, in this case. The method addrole creates a new link between the receiver of the method and an instance of the class B passed as argument. If the argument of the method is null, the method does nothing. The method removerole deletes the link between the receiver of the method and the instance of the class B passed as argument. If no such link exists, or if the argument is null, the method call has no effect. The method getroleset returns the set of instances of the class B that have a link with the receiver of the method. The value returned by this method is always an instance of a class that implements the java.util.set interface. The remaining three methods are equivalent to the following expressions: obj.getrolecount() is equivalent to the expression obj.getroleset().size() obj.hasanyrole() is equivalent to the expression (! obj.getroleset().isempty()) obj.hasrole(b) is equivalent to the expression obj.getroleset().contains(b) In the current version of the Fénix Framework, the hasrole() and hasanyrole() methods are no longer generated and the getrolecount() is deprecated and therefore it should not be used. Including all this in our example, we get the following class diagram, concerning just the Person and Contact classes: ES 2014/15 [ 21 / 50 ]

22 Person 1 * Contact contact:set<contact> +getcontactset:set<contact> +getcontactcount(): int +hasanycontact(): boolean +hascontact(contact): boolean +addcontac(contact): void +removecontact(contact): void name:string phonenumber: int person: Person +getname(): String +setname(string): void +getphonenumber(): int +setphonenumer(int): void +setperson(persn): void +hasperson(): boolean You must read the documentation concerning the DML, available in framework.github.io/dml.html You may find basic documentation in this excerpt 1 of the PhD thesis that introduced the DML. More advanced (and newly) aspects of the DML language are described in this doc. ES 2014/15 [ 22 / 50 ]

23 Lesson 3.3: Defining the root object The applications developed using the Fénix Framework must have a special object called the root object. The root object provides a way to access the persistent state of the application. It is the entry point of the application persistent state. In the Fénix framework, the root object is always the single instance of the DomainRoot class. This class is already provided by the Fénix Framework. Then, you just need to connect the domain model of your application with the DomainRoot class. In this example, we just need to connect the PhoneBook class with the DomainRoot class. Since there should be a single PhoneBook instance in the PhoneBook application, we need to establish a one- to- one relation between the PhoneBook and DomainRoot classes. Therefore, we need to add the following declaration to the DML file of this application: 1. relation PersonContainsContacts { 2. PhoneBook playsrole phonebook { multiplicity 0..1 }; 3..pt.ist.fenixframework.DomainRoot playsrole root { multiplicity 0..1; } 4. } Lesson 3.4: Generating the Fénix Framework related code The process of building an application that uses the Fénix Framework is relatively complex due to both code generation tasks and the required post- processing steps applied to the compiled classes. However, this complex building process can be eased and simplified by using a build tool such as Maven where you can use specific plugins defined by the Fénix team for executing the Fénix Framework specific tasks. Consider the following POM file for the PhoneBook application: 1. <project xmlns=" xmlns:xsi=" instance" 2. xsi:schemalocation=" xsd"> 3. <modelversion>4.0.0</modelversion> <groupid>pt.tecnico</groupid> 6. <artifactid>phonebook</artifactid> 7. <version> SNAPSHOT</version> 8. <packaging>jar</packaging> <name>phonebook</name> <properties> 13. <java.version>1.8</java.version> <project.build.sourceencoding>utf- 8</project.build.sourceEncoding> 16. <project.reporting.outputencoding>utf- 8</project.reporting.outputEncoding> <fenix.framework.codegeneratorclassname>pt.ist.fenixframework.backend.jvstmojb.codegenerat or.fenixcodegeneratoroneboxperobject</fenix.framework.codegeneratorclassname> 19. <fenix.framework.backend>jvstm- ojb</fenix.framework.backend> 20. <version.pt.ist.fenix.framework>2.6.0</version.pt.ist.fenix.framework> <version.junit>4.11</version.junit> 23. <version.slf4j.api>1.7.7</version.slf4j.api> 24. <version.ch.qos.logback.classic>1.1.2</version.ch.qos.logback.classic> 25. </properties> <build> 28. <plugins> ES 2014/15 [ 23 / 50 ]

24 29. <plugin> 30. <groupid>org.apache.maven.plugins</groupid> 31. <artifactid>maven- compiler- plugin</artifactid> 32. <version>3.1</version> 33. <configuration> 34. <source>${java.version}</source> 35. <target>${java.version}</target> 36. <verbose>true</verbose> 37. <fork>true</fork> 38. </configuration> 39. </plugin> 40. <plugin> 41. <groupid>pt.ist</groupid> 42. <artifactid>ff- maven- plugin</artifactid> 43. <version>${version.pt.ist.fenix.framework}</version> 44. <configuration> 45. <codegeneratorclassname>${fenix.framework.codegeneratorclassname}</codegeneratorclassname> 46. </configuration> 47. <executions> 48. <execution> 49. <id>default</id> 50. <goals> 51. <goal>ff- generate- domain</goal> 52. <goal>ff- process- atomic- annotations</goal> 53. </goals> 54. </execution> 55. </executions> 56. <dependencies> 57. <dependency> 58. <groupid>pt.ist</groupid> 59. <artifactid>fenix- framework- backend- ${fenix.framework.backend}- code- generator</artifactid> 60. <version>${version.pt.ist.fenix.framework}</version> 61. </dependency> 62. </dependencies> 63. </plugin> <plugin> 66. <groupid>org.codehaus.mojo</groupid> 67. <artifactid>exec- maven- plugin</artifactid> 68. <version>1.3.2</version> 69. <executions> 70. <execution> 71. <goals> 72. <goal>java</goal> 73. </goals> 74. </execution> 75. </executions> 76. <configuration> 77. <mainclass>pt.tecnico.phonebook.phonebookapplication</mainclass> 78. <killafter>- 1</killAfter> 79. </configuration> 80. </plugin> 81. </plugins> 82. </build> <dependencies> 85. <dependency> 86. <groupid>pt.ist</groupid> 87. <artifactid>fenix- framework- core- api</artifactid> 88. <version>${version.pt.ist.fenix.framework}</version> 89. </dependency> 90. <dependency> 91. <groupid>pt.ist</groupid> ES 2014/15 [ 24 / 50 ]

25 92. <artifactid>fenix- framework- core- consistency- predicates</artifactid> 93. <version>${version.pt.ist.fenix.framework}</version> 94. </dependency> 95. <dependency> 96. <groupid>pt.ist</groupid> 97. <artifactid>fenix- framework- backend- ${fenix.framework.backend}- runtime</artifactid> 98. <version>${version.pt.ist.fenix.framework}</version> 99. </dependency> 100. <dependency> 101. <groupid>junit</groupid> 102. <artifactid>junit</artifactid> 103. <version>${version.junit}</version> 104. <scope>test</scope> 105. </dependency> 106. <dependency> 107. <groupid>org.slf4j</groupid> 108. <artifactid>slf4j- api</artifactid> 109. <version>${version.slf4j.api}</version> 110. </dependency> 111. <dependency> 112. <groupid>ch.qos.logback</groupid> 113. <artifactid>logback- classic</artifactid> 114. <version>${version.ch.qos.logback.classic}</version> 115. </dependency> 116. </dependencies> <repositories> 119. <repository> 120. <id>fenixedu- maven- repository</id> 121. <url> maven- repository</url> 122. </repository> 123. </repositories> <pluginrepositories> 126. <pluginrepository> 127. <id>fenixedu- maven- repository</id> 128. <url> maven- repository</url> 129. </pluginrepository> 130. </pluginrepositories> 131. </project> Listing 1: The generic POM file for a Fénix Framework application. This POM file can be used for any Maven project that should use the Fénix Framework. You only need to change the values defined for the groupid and artifactid elements (lines 5 and 6 of pom.xml) of the new project. You also need to change the Java class to execute (see line 78) when the goal exec:java is executed. This file also specifies the execution of three goals that are specific to the Fénix Framework code: ff- generate- domain corresponds to the taks that processes the DML file and generates the base classes, and the empty behavior classes (if they do not already exist). ff- process- atomic- annotations adds transactional behavior to methods marked with annotation. You also have to define the directory structure of your Maven project. Considering the PhoneBook application, the first thing to do is to create the home directory of this Maven project and then copy this POM file to this directory. Then, you need to create the standard ES 2014/15 [ 25 / 50 ]

26 directory structure of a Maven project. In this case, it is necessary to create src/main/java/pt/tecnico/phonebook and src/test/java/pt/tecnico/phonebook. You also have to create the directory src/main/dml. This directory will hold the dml file of this project. Finally, you will have to create src/main/resources directory. This directory contains the file fenix- framework- jvstm- ojb.properties. This file specifies the information needed by the Fénix Framework to connect to the database system that stores the persistent data of the application. You need to specify the values for three properties that specify the parameters needed to connect to the database: dbalias represents the name of the database that holds the persistent state of the application. dbusername is the username of the user used to access to the database. dbpassword is the password of the user specified in dbusername. For example, this file could have the following (using the root user and rootroot as the password for this user): 1. # using special INFER_APP_NAME to do just that 2. appname=infer_app_name dbalias=//localhost:3306/phonebook?useunicode=true&characterencoding=utf- 8&clobCharacterEncoding=UTF- 8&zeroDateTimeBehavior=convertToNull 5. dbusername=root 6. dbpassword=rootroot Notice that you need to create the phonebook database in your database system before starting the execution of the PhoneBook application. If you use the mysql client to access to the database system, you should execute the following sql command: create database phonebook;. ES 2014/15 [ 26 / 50 ]

27 Lesson 3.5: Implementing the Business Logic To implement the business logic, first you need to generate the base classes that represent the structural aspects of the application domain model. This can be achieved by executing mvn compile. This Maven lifecycle phase was customized and now this phase also processes the given DML file that describes the domain model of our application. As we saw, the name of a generated base class is equal to the name of the entity of the application domain model it represents with the _Base suffix. The name of the behavior classes is equal to the name of the entities they represent in the application domain model. These classes are generated in the target directory of the Maven project since they correspond to code automatically generated during the build of the project. The first time this phase is executed, it also generates the empty behavior classes that should hold the domain logic of our application. These classes (PhoneBook.java, Person.java and Contact.java) are located at the src/main/java/pt/tecnico/phonebook/domain directory since the package of the application domain specified in the DML file was pt.tecnico.phonebook.domain. Given that we only defined three classes in our domain model, we will make a simple example by just editing the empty Contact class: 1. public class Contact extends Contact_Base { public Contact() { 4. super(); 5. } } The previous source code exemplifies the empty class generated by the DML compiler. It will only be created if this file does not exist when the base classes are generated. That way, any implemented business logic that we have already implemented meanwhile is not deleted. In order to create new contacts and associate them values for their name and their phone number fields, we must modify the empty generated constructor of our Contact class to accept such parameters and use the inherited setters from the Contact_Base class to set their value: 1. public class Contact extends Contact_Base { public Contact(String name, String phonenumber) { 4. this.setname(name); 5. this.setphonenumber(phonenumber); 6. } } Apart from the inherited data field accessors (setters and getters) defined in the DML file, the DML compiler also generates the source code for the relations defined in the same file. In this case, we can call the getperson() method on a Contact instance that will return the Person instance holding that Contact instance. On the Person class, we can call the addcontact(...) method, inherited from the Person_base class, to add a new contact to the PhoneBook instance. The Fénix Framework implements these methods considering the bi- directionality of the relation. Therefore, we only need to call either the setperson(...) method in a Contact instance, or the addcontact(...) in a Person instance to establish a relation between a these two instances, because the result is the same. ES 2014/15 [ 27 / 50 ]