Managing model behavior using aspects and augments

You can use aspects and augments to simplify the configuration of classes and data sources in your model.

You can use aspects to apply groups of attributes and events to multiple classes or data sources. You can use augments to extend an existing class or data source without editing the original code.

Info

To create augments, you must enable Support Metadata Augments in NexJ Studio. Data source augments are only supported for relational databases.

Managing class behavior through aspects

A class aspect represents a functional grouping of attributes that you can apply to one or more classes. Class aspects enable you to manage class attributes without having to edit individual classes. Aspects can be in a different business model than the classes they enhance.

Class aspects differ from classes and do not impact the application until they are applied to a class. Applying an aspect to a class adds the behavior defined in the aspect to the class. For example, when you apply the DELETE_RO aspect to the Entity class, you incorporate the definition of the DELETE_RO aspect into the Entity class. Class aspects display with the Aspects icon

Aspects are useful for managing cross-cutting concerns such as logging, security, and data transfer. You can incorporate the behavior of an existing class aspect into a new class aspect by adding the existing class aspect to the new class aspect. Aspects can include actions to existing class events. You can define the sequence in which class and aspect actions occur.

When creating an aspect, you must specify the pointcuts at which the aspect applies. A pointcut defines the join points at which an aspect must be applied. A join point is a point in the execution of a program at which additional code is added because of advice specified in a corresponding pointcut.

At any time, you can edit an aspect to include additional classes or edit a class to include additional aspects. You can also exclude classes from an aspect and exclude aspects from a class.

Info

If an attribute or an event is defined differently in a class and an aspect applied to the class, the behavior defined in the class applies.

Creating class aspects

Create class aspects from the Business Model layer in NexJ Studio.

If you do not know the data sources to which a class aspect will be mapped, you can also create a corresponding data source aspect and map the class aspect to it. This enables you to apply the class aspect to all future data sources created in the model without having to edit the class aspect.

To create a new class aspect:

1. In the Business Model layer, click the Classes tab.
2. Right-click in the navigator and select New Class Aspect.
3. Enter a name for the aspect and click Finish.

Info

NexJ recommends using upper case for aspect names for consistency with the naming convention in the base model that NexJ provides.

You have created a new class aspect.

You can now apply the aspect to classes and exclude the aspect from classes as neede

Applying aspects to classes

You can apply aspects to classes either by editing aspects to include classes or editing classes to include aspects. When editing an aspect to include classes, you specify pointcuts. When doing so, you can use the asterisk (*) and question mark (?) wildcard characters to expand the set of classes the aspect applies to.

To apply an aspect to a class:
1. In the Business Model layer, click the Classes tab.
2. Do one of the following:

• To edit an aspect to include classes:
  1. Double-click the aspect to open it.
  2. In the Overview tab, in the Pointcuts field, enter a list of name patterns of the classes you want to add the aspect to. For example, to apply the aspect to all classes in the tr module, enter tr:* in Pointcuts.
  3. Click the Save button to save your changes.
• To edit a class to include an aspect:
  1. Double-click the class to open it.
  2. In the Overview tab, in the Aspects field, click Select.
  3. Select the aspect you want to apply to the class and click Include.
  4. Click OK to save your changes.

The aspect is applied to the specified classes. The class behavior now includes the aspect definition.

Excluding aspects from classes

If you do not want an aspect to apply to a specific class, you can either edit the aspect to exclude the class or edit the class to exclude the aspect. When editing an aspect to exclude classes, you specify pointcuts. When doing so, you use the exclamation mark (!) wildcard character to indicate exclusion. You can use this wildcard character in combination with the asterisk (*) and question mark (?) wildcard characters to expand the set of classes that exclude the aspect.

To exclude an aspect from a class:

1. In the Business Model layer, click the Classes tab.
2. Do one of the following:
   • To edit an aspect to exclude a class:
     1. Double-click the aspect to open it.
     2. In the Overview tab, in the Pointcuts field, enter ! followed by the name of the class you want to exclude the aspect from. For example, !tr:Log.
     3. Click the Save button

        

        to save your changes.
   • To edit a class to exclude an aspect:
     1. Double-click the class to open it.
     2. In the Overview tab, in the Aspects field, click Select.
     3. Select the aspect you want to exclude from the class and click Exclude.
     4. Click OK to save your changes.

The aspect is excluded from the specified class. The aspect definition no longer impacts the class behavior.

Managing data source behavior through aspects

To apply a class aspect to classes mapped to multiple data sources, instead of mapping the aspect to each data source, you can create a data source aspect and map the class aspect to it. Data source aspects enable you to persist class aspects to multiple data sources, including future data sources created in a model. Aspects can be in a different model than the data sources they enhance.

Info

If there is a conflict between the definition of a data source and an aspect applied to the data source, the data source definition applies.

Data source aspects differ from data sources and do not impact the application until they are applied to a data source. Data source aspects display with the Aspects icon

Info

Data source aspects are only supported for relational databases.

Creating data source aspects

Create data source aspects from the Persistence layer in NexJ Studio.

To create a new data source aspect:

1. In the Persistence layer, click the Data Sources tab.
2. Right-click in the navigator and select New Relational Database Aspect.
3. Enter a name for the aspect and click Finish.

Info

NexJ recommends using upper case for aspect names for consistency with the naming convention in the base model that NexJ provides.

You have created a new data source aspect.

You can now apply the aspect to data sources and exclude the aspect from data sources as needed.

Applying aspects to data sources

You can apply aspects to data sources either by editing aspects to include data sources or editing data sources to include aspects. When editing an aspect to include data sources, you specify pointcuts. When doing so, you can use the asterisk (*) and question mark (?) wildcard characters to expand the set of data sources the aspect applies to.

To apply an aspect to a data source:

1. In the Persistence layer, click the Data Sources tab.
2. Do one of the following:
   • To edit an aspect to include data sources:
     1. Double-click the aspect to open it.
     2. In the Overview tab, in the Pointcuts field, enter a list of name patterns of the data sources you want to add the aspect to. For example, to apply the aspect to all data sources in the tr module, enter tr:* in Pointcuts.
     3. Click the Save button

        

        to save your changes.
   • To edit a data source to include an aspect:
     1. Double-click the data source to open it.
     2. In the Overview tab, in the Aspects field, click Select.
     3. Select the aspect you want to apply to the data source and click Include.
     4. Click OK to save your changes.

The aspect is applied to the specified data sources. The data source behavior now includes the aspect definition.

Excluding aspects from data sources

If you do not want an aspect to apply to a specific data source, you can either edit the aspect to exclude the data source or edit the data source to exclude the aspect. When editing an aspect to exclude data sources, you specify pointcuts. When doing so, you use the exclamation mark (!) wildcard character to indicate exclusion. You can use this wildcard character in combination with the asterisk (*) and question mark (?) wildcard characters to expand the set of data sources that exclude the aspect.

To exclude an aspect from a data source:

1. In the Persistence layer, click the Data Sources tab.
2. Do one of the following:
   • To edit an aspect to exclude a data source:
     1. Double-click the aspect to open it.
     2. In the Overview tab, in the Pointcuts field, enter ! followed by the name of the data source you want to exclude the aspect from. For example, !tr:LogDatabase.
     3. Click the Save button

        

        to save your changes.
   • To edit a data source to exclude an aspect:
     1. Double-click the data source to open it.
     2. In the Overview tab, in the Aspects field, click Select.
     3. Select the aspect you want to exclude from the data source and click Exclude.
     4. Click OK to save your changes.

The aspect is excluded from the specified data source. The aspect definition no longer impacts the data source behavior.

Example of class and data source aspects

This example shows how you can apply the behavior of the DELETE_RO aspect from an existing model to all classes in another model, except to a class named tr:Log.

Info

The DELETE_RO aspect ensures that class instances are only soft deleted. Soft deleted data remains in the backend for retrieval if necessary.

To apply the DELETE_RO aspect to classes:

1. Create a new model named tr with the module prefix tr.
2. In the new model, create a class aspect named tr:DELETE_RO and apply the DELETE_RO class aspect to it.
3. Set the pointcuts for the new aspect to tr:*.
4. Create a new class named tr:Log.
5. Exclude the tr:DELETE_RO aspect from the new class. You can do this either by selecting the tr:DELETE_RO aspect in the Select Aspect field for the tr:Log class and clicking Exclude, or by entering !tr:Log in the Pointcuts field for the tr:DELETE_RO aspect.
6. Create a new relational database aspect named tr:DELETE_RO_DATABASE.
7. Set the pointcuts for the aspect to tr:*.
8. Map the tr:DELETE_RO class aspect to the tr:DELETE_RO_DATABASE data source aspect.

The tr:DELETE_RO aspect is applied to all classes in the tr model except the tr:Log class. The behavior defined in the tr:DELETE_RO class aspect and the tr:DELETE_RO_DATABASE data source aspect, respectively, will apply to any new classes and data sources created in the tr model.

Extending classes through augments

You can use class augments to extend the behavior of a class without having to modify the class or create a new class. When you augment a class, a separate class augment is created with the customized class details and theoriginal source code of the class remains unchanged. Unlike class customizations, augments cannot override the base model, which prevents collisions between the base model and the class customization. Using augments eliminates the need to merge the base model into the customization during upgrades.

Info

Augments are useful to extend individual classes. To customize multiple classes simultaneously, NexJ recommends using class aspects instead.

To augment classes, you must first enable support for augments in NexJ Studio by navigating to Window →Preferences → NexJ Studio and selecting Support Metadata Augments.

To create a new class augment:

1. In the Business Model layer, click the Classes tab.
2. Right-click in the navigator and select New Class Augment.
3. Enter a name for the augment.
4. In the For field, click Select Class and select the class to augment.

5. Click OK and then click Finish.

You have created a new class augment, which you can edit as needed to extend the functionality of the original class.

Related Links

Managing class behavior through aspects
Configuring NexJ Studio preferences 

Extending data sources through augments

You can use data source augments to extend a data source definition without having to modify the data source or create a new data source. When you augment a class, the associated data sources will not contain the additional columns required to support the enhanced functionality in the augmented class. Therefore, when you create a class augment, you must also create a corresponding data source augment with these additional columns.

To create a data source augment:

1. In the Persistence layer, click the Data Sources tab.
2. Right-click in the navigator and select New Relational Database Augment.
3. Enter a name for the augment.
4. In the For field, click Select Database and select the data source you are augmenting.
5. Click OK and then click Finish.

You have created a new data source augment, which you can edit as needed to extend the original data source definition.

Example of class and data source augments

This example shows how to extend the Address class from an existing model into a new model to display the latitude and longitude for addresses in the new model.

To extend the Address class:

1. Create a new model named tr.
2. In the new model, create a class augment named tr:Address for the Address class in the base model, which is mapped to the DefaultRelationalDatabase data source.
3. Add two calculated attributes named latitude and longitude to the tr:Address augment.
4. Create a new relational database augment named tr:DefaultRelationalDatabase for the DefaultRelationalDatabase data source.
5. Add a table named tr_Geo to the tr:DefaultRelationalDatabase augment with the columns required to support the enhanced functionality in the tr:Address augment.
6. Map the tr:Address class augment to the DefaultRelationalDatabase data source with tr_Geo set as the primary table.

All addresses in the new model will include latitude and longitude in addition to the attributes defined in the original Address class.