ToolsTutorial02

Welcome to the FrameWeb Tools Tutorial. This is part 02 of the tutorial, so if you got here directly you might want to start from the beginning of the tutorial.

FrameWeb Tools Tutorial, Part 02: using the editor

In this part of the tutorial, we will activate the FrameWeb Facet in our project and create FrameWeb models that represent a simple new feature for the Oldenburg system: student registration.

Activate the FrameWeb Facet

Once the FrameWeb Tools have been installed and Eclipse restarted, we need to activate the FrameWeb Facet in our project, as follows:

1. In the Project Explorer, right-click the oldenburg project and select Properties;
2. In the Project Facets page, select FrameWeb Editor and click Apply and Close.

At this point, there might be a problem: the FrameWeb Editor facet does not show at the Project Facets page if your project uses a target runtime that is, for some reason, incompatible with our plug-in. If this happens to you, the workaround is to remove the target runtime (Properties > Targeted Runtimes page) then configure JSF and JPA to Disable Library Configuration (Project Facets page). Then, add the jakarta.platform / jakarta.jakartaee-api 8.0.0 as a provided dependency in your pom.xml as instructed in the JButler tutorial.

If everything went well, you should see two new files in your project: Configuration.frameweb and Model.frameweb.

Import the Architecture Definition Files

The FrameWeb Tools use a set of files that define the architecture of the project being modeled, including the definition of primitive types and classes from the API of your programming language of choice (e.g., Java has int, double, String, etc.) to be used as types of attributes in different models; tags from your visual component library of choice (e.g., PrimeFaces has dataTable, inputText, password, etc.); and templates for code generation (which we will see in the next step). Hence, we need to import these architecture definition files into our project. Here is how this is currently done:

1. As a suggestion to keep things organized, create a folder called frameweb in the oldenburg project;
2. Visit the nemo-ufes/FrameWeb source code repository and clone or download it;
3. In the cloned/downloaded repository, look for the languages folder and copy the Java.frameweb file to the frameweb folder in your project;
4. Then, look for the frameworks folder and copy the jbutler folder to the frameweb folder in your project;
5. The FrameWeb Tools should load the templates automatically.

The jbutler files contain tags and templates to be used with a JButler project, considering the Jakarta EE standards JSF, CDI, EJB and JPA, the visual components library PrimeFaces and AdminFaces theme.

Create your models

We're all set to create some FrameWeb models now. Currently, to open the FrameWeb Editor, one must follow these steps:

1. Click on the menu Window > Perspective > Open Perspective > Other..., choose the Sirius perspective and click Open;
2. In the Model Explorer view, using the gray triangle/arrow, expand the Model.frameweb file from the oldenburg project;
3. Right-click the Project element and click on New Representation > new FrameWeb Project menu;
4. Give a name to your project (or keep the default value) and click OK;
5. The FrameWeb Editor will open, showing all the templates that have already been loaded (Java and JButler templates), as well as the FrameWeb Configuration. The figure below shows an example of a newly created project open in the FrameWeb Editor (boxes have been moved closer together);
6. To create a given model, click on the type of model at the palette at the right-hand side of the editor and click on an empty space of the editor. Then, double click the package that is automatically added there and click OK.

If you close the editors, to open them back you should again expand the Model.frameweb file from the oldenburg project in the Model Explorer view, expand the Project element inside it and double-click on the model you would like to open.

As stated before, we will implement a simple Registration feature in Oldenburg. In the FrameWeb Entity Model (i.e., in the domain package), we will have a class to represent authors that submit papers to workshops managed by Oldenburg. Here are some tips to create an Entity Model:

• Classes exist inside packages, so the first element you should create is the Domain Package;
• Give your Domain Package its proper name (e.g., br.ufes.informatica.oldenburg.core.domain) by changing the value of Name in the Properties view that should be showing in the bottom part of the screen. Use that view to change the properties of different elements of the model;
• Use the DomainClass component in the palette to add entities to your model;
• Explore the Attributes and Methods section of the palette to see the types of attributes that can be added to a DomainClass. ID, Version, Decimal, dateTime and LOB attributes have their own items. All other attributes should use Domain Attribute;
• When using JButler, there's no need to add ID and version attributes to entity classes, as they all implicitly inherit from PersistentObjectSupport (in this case make sure you mention it in the documentation).

The figure below shows the Entity Model for our simple example:

Next, we create and open a Persistence Model. In this model, we create a Persistence Package br.ufes.informatica.oldenburg.core.persistence and, inside it, a DAO Interface AuthorDAO and a DAO Class AuthorDAOJPA that realizes the interface. Our DAO should have a single method that retrieves an author given their e-mail in order to check if an author has already been registered under that e-mail. To add parameters to the method, double click it and a method editor will open. Use the palette to add parameters, the Properties view to set their name and type, then save and close to see it in the Persistence Model using the UML syntax. Also, return types are set using the Method Type property, not the Type property.

Naming convention note: JButler templates expect all DAO interfaces to have the DAO suffix (e.g., AuthorDAO) and all implementations to have the same name of their realized interfaces, plus a JPA suffix (e.g., AuthorDAOJPA). Code generation will work better if you follow this naming convention.

When using JButler, DAO interfaces implicitly inherit from BaseDAO and implementations from BaseJPADAO. The figure below shows the result for the Persistence Model.

Then we move on to the Navigation Model, creating a View Package /core/registration/ and a Controller Package br.ufes.informatica.oldenburg.core.controller. Here are some tips to create a Navigation Model:

• Create pages using the Page component at the palette and give them a name without the .xhtml extension, as this will be added later by the code generator;
• Create forms using the UI Component component at the palette. Form fields are created with UIComponentField and their type should be one of the tags from your visual component library (in our case, PrimeFaces);
• When selecting the type of the tag from the dropdown list, if you type the name of the Tag the list will be filtered, but you have to start from the beginning (e.g., type Tag input to see the different PrimeFaces tags that start with input);
• Form fields (UIComponentField) can also be added to pages directly;
• To link a page to a form, use the Navigation Association component from the palette (I know, these names are not intuitive at all, we'll work on that...);
• Moving to the controller side, a Front Controller Class can get attributes via IOParameter component and methods via Front Controller Method component from the palette;
• To connect a page or form to a controller, use Front Controller Dependency and select one of the methods from the controller in the the Method property;
• To connect a controller to a page, use the Result Dependency and select one of the methods from the controller in the the Result Method property. Further, click on the Result Constraints section and set the result and AJAX constraints if applicable.

Naming convention note: JButler templates expect all controller classes to have the Controller suffix (e.g., RegistrationController). Code generation will work better if you follow this naming convention.

The figure below shows the result for the Navigation Model.

Finally, we create an Application Model, which will already display our controller class and package and our DAO class and its package. We create an Application Package br.ufes.informatica.oldenburg.core.application, with a Service Interface RegistrationService and a Service Class RegistrationServiceBean that realizes the interface. Using a ServiceControllerAssociation we connect our controller to the service interface. Then, using a DAOServiceAssociation we connect our service class with out DAO. Finally we add a method to the service class, the same way we did in other models before. The figure below shows the result for the Application Model.

Naming convention note: JButler templates expect all service implementations to have the same name of their realized interfaces, plus a Bean or a Impl suffix (e.g., RegistrationServiceBean). Code generation will work better if you follow this naming convention.

In case of problems...

In case the model was not able to be built the way you expected, you could create a new issue in FrameWeb's issue tracker so we could try to fix it in the next version of the FrameWeb Tools. Please describe the issue (in English or Portuguese) as detailed as possible so we can try to reproduce it and then develop a fix, if applicable.

Try to evaluate, however, if the issue you are facing is due to the fact that you are designing a system to an architecture that is not currently supported by FrameWeb Tools. For more information about this, see the part 4 of the tutorial.

Next: generating code