MetaBoss Programming Model Guide.

Business Objects.

Index

Definition

Business Objects are java classes, which represent data entities this enterprise operates with. For example stockbroking business would operate with Clients, Orders, Stocks, Invoices, Settlements etc. Each one of these things is usually represented by business entity on the domain entity model. Business entities may be grouped into the separate domains, with each domain given responsibility for a particular area of business. For each modelled domain MetaBoss generates so called Business Objects package - a dedicated package where all business entity related interfaces are located. The role of elements of this package is to allow Java programmer to seamlessly navigate around entities in domain and manipulate their contents. The Business Objects package contains following types of interfaces:

• Business Object Domain - one per Business Domain (i.e. only one in each package). Serves as an entry point to all domain operations. In relational database terms maps to a schema.
• Business Object - one per Business Entity. Represents single instance of the Business Entity. In relational database terms maps to a single record in the table where all Business Entities of particular type are stored.
• Business Object Collection - one per Business Entity. Represents collection of instances of Business Entities. In relational database terms maps to a result set returned from the query where each element of the result set represents full record from the table where all Business Entities of particular type are stored.
• Business Object Report - as many as modelled. Represents custom, non-standard query returning collection of values organised in denormalised hierarchy.

Programming Model Overview

MetaBoss generators create Business Object libraries, which follow certain programming model. Key elements of this model are:

Business Object Domain overview

Each business object package contains one and only one interface representing whole domain. Its name is generated by default as 'BODomain'. This object is the entry point to the domain, meaning that every operation on domain must start from this object. This interface is the only componentised interface, which could be accessed via JNDI. New copy of BODomain is returned every time it is looked up, so it is similar to opening a separate connection. All other elements of the Business Objects package must be accessed from Business Object Domain by calling its member methods. Most of these member methods are generated for each entity with Business Entity Name or Plural Name (whichever is more appropriate) forming part of the method name. The Business Object Domain has following methods for each Business Entity in the domain:

• get<Business Entity Name>(<Business Entity Instance Id>)
  This method returns a single instance of Business Object with matching instance identifier. It throws exception if desired instance is not found.
  
• get<Business Entity Name>(<Business Entity Natural Primary Key>)
  This method returns a single instance of Business Object with matching natural primary key or null if Business Object with matching natural primary key does not exist. This method is only present for entities with specified natural primary key.
  
• getAll<Business Entity Plural Name>()
  This method returns a single instance of Business Object Collection matching all instance of Business Objects in the domain.
  
• get<Business Entity Name>ForEditing(<Business Entity Instance Id>,<Business Entity Instance Version Id>)
  This method returns a single instance of Business Object with matching instance identifier and version identifier. Returned object is placed in editable state. This method requires curent active transaction. It throws exception if desired instance is not found or the stored version identifier does not match supplied one.
  
• create<Business Entity Name>(<Business Entity Natural Primary Key>)
  This method returns a newly created single instance of Business Object initialised with supplied natural primary key elements. This method requires curent active transaction. This method is only generated for the 'top level' entities - the entities which are not contained by any other entity.
  
• get<Business Report Name>Report(<Business Report Inputs>)
  This method returns a newly created single instance of Business Object Report as a single page containing whole report. Report is generated with supplied input parameters. This method is generated for every report in the domain model.
  
• get<Business Report Name>ReportPage(PageOffset, PageSize, <Business Report Inputs>)
  This method returns a newly created single instance of Business Object Report as a single page containing part of the report. Report is generated with supplied input parameters. This method is generated for every report in the domain model, which has pagination facility.
  

Business Object overview

As it has been mentioned above, Business Object represents an instance of the particuar entity. Once created, Business Object can not change its identity, it means that same instance of Business Object can never change the Business Entity instance it represents. Reverse is also true - same instance of Business Entity can only be represented by single instance of Business Object (providing we are working in the same BODomain). Every Business Object class has following features:

• The Instance Id attribute is accessible via the getter method. Instance Id is generated at the entity creation time and can never be modified, therefore the setter method for this attribute is absent.
• The Version Id attribute is present and accessible via getter method only for editable entity (driven by stereotype in the model). Version Id is automatically advanced every time entity is updated, therefore the setter method for this attribute is absent.
• The State attribute is present and accessible via getter method only for entities with a state machine (driven by the model). Setter method is also available for changing the state. Certain rules needs to be followed when updating state:
  • When new entity instance is created, the initial state is set automatically, so there is no need to set it.
  • Only modelled state transitions could be executed. State setter method will fail and throw exception if attempt is made to make an illegal state transition.
  • Only one state transition per transaction can be executed. State setter method will fail and throw exception if attempt is made to call it for the second time without committing transaction first. This rule is ensuring that every state transition is visible at the storage medium (if only for a fraction of a second) and therefore all possible database triggers and events will be fired.
• All attributes of the entity are accessible via getter methods. For editable entities (driven by stereotype in the model), setter methods will be present for all attributes excluding attributes with certain stereotypes, such as UpdateStamp and CreateStamp. Values for these special types of attributes are automatically generated and therefore setters are not required.
• All associated entities are accessible via getter methods. For singular cardinality references (e.g. 'Zero or One' or 'Exactly One') getter is returning a Business Object representing associated entity. For plural cardinality references (e.g. 'Zero or More' or 'One or More'), the getter is returning a Business Object Collection representing a collection of the associated entities. If entity is the owner of the associated entity, the creator method will be present. This enforces that owner instance is present before owned instance can be created. If entity is a user of the associated entity it will have a methods to set and clear the association. For singular cardinality association these methods will be named set.... and clear.... For plural cardinality these methods will be named add.... and remove....

Business Object Collection overview

Business Object Collection represents a collection of entity instances of the particuar type. It has following features:

• A number of contains... methods allowing to query if certain entity belongs to collection or not.
• A getter methods, which will only return requested Business Object (identified by Instance Id or Natural Primary Key) if this object is part of the collection.
• isEmpty() method returns true if collection has no members.
• size() method returns count of elements in the collection.
• toArray() methods return whole or part of the collection as Java array.
• union(), intersection() and difference() methods return result of the corresponding set operation as another collection.
• Selector methods (driven from the model) return result of the corresponding select operation as another Business Object Collection or single Business Object, depending on selector cardinality.
• All associated entities are accessible via associated Business Object Collection getter methods.

When working with collections it is important to remember that the underlying implementation of the collections defers actual query call to persistance layer for as long as possible, therefore minimising amount of calls to remote storage. Only certain calls, such as toArray(), isEmpty() etc, are actually result is persistance layer calls. Set operation methods, selector methods and related associations navigation methods are only manipulating collection objects in memory and not executing actual queries to the persistence layer.

Business Object Collections are not transactional and do not offer any methods to modify collections. All methods to create or delete or add or remove Business Objects can be found in Business Domain and Business Object classes.

Business Object Report overview

Business Object Report represents an output of the manually defined hand-coded query. Its role is to allow access to the data attributes in the report in the way consistant with the way entity attributes are accessed. There is one Business Object Report generated for each level of each report. Each object has getters for all fields of the report at the level this object is corresponding to. Naturally there are no setters for any of the report fields. If some element of report output are defined in the model in terms of entities, the getter method for the entity will be present in the report object.

Annotated Example