skip to main content
TGO > Programmers documentation > Business objects and data sources > The business model > Business model API
 
Business model API
Describes the API of the components of a business model: business classes, business objects, and attributes.
*Class overview
*Provides a diagram of the different classes involved in a business model.
*Business class API
*Describes the business class interfaces and their implementations.
*Business object API
*Describes the business object interfaces and their implementations.
*Attribute API
*Describes the attribute-related interfaces and their implementations.
Class overview
The business model API is composed of the following APIs:
*Business class API
*Business object API
*Attribute API
The following figure illustrates the various elements that compose the business object model.
The business model API
Business class API
The interface IlpClass defines static classes. It provides methods to:
*Retrieve the class structure, that is, its superclass and subclasses
*Retrieve the associated attributes, that is, the attribute group
The interface IlpMutableClass defines dynamic classes. In addition to the methods listed above, it provides methods to:
*Add and remove attributes
*Aggregate attribute groups to the class
*Notify listeners about these modifications
JViews TGO provides a few convenience implementations of these interfaces that you can use directly or subclass when building an application:
*IlpAbstractClass—An abstract implementation that helps you create new IlpMutableClass implementations.
*IlpDefaultClass—A default implementation for a dynamic class.
*IlpBeansClass—A wrapper for an existing JavaBean™ class that makes it possible to access it (through introspection) as if it were a dynamic class. Properties discovered during introspection are automatically translated to IlpBeansAttribute instances and inserted in the class attribute group.
Business object API
The interface IlpObject defines instances of business classes. These instances (business objects) contain values for the attributes defined by the corresponding class. They also have an attribute group that can be the IlpClass itself or an extension allowing you to define new attributes at the object level.
Each business object must be assigned to an identifier when it is created. The identifier must be unique (even across data sources); it is used to identify and retrieve the IlpObject. The object identifier can be of any type, as long as it satisfies the following constraints:
1. The identifier must be convertible to String, through an IlpTypeConverter installed in the IlpContext. The IlpDefaultTypeConverter uses the Object.toString() method to convert objects of unknown types to String. The String that results from this conversion must be unique.
2. It must be possible to create or retrieve the identifier Object, given the corresponding String, by using the IlpTypeConverter installed in the IlpContext. The IlpDefaultTypeConverter uses a constructor with a single String argument to create instances of unknown types.
3. The identifier Object itself must not be an instance of IlpObject.
Note the following recommendations:
*Ideally the identifier should be implemented as a simple object in order to perform a fast comparison. For the sake of simplicity, it is recommended to use simple objects, such as Number or String, which already satisfy the constraints listed above.
*If you are using your own Java™ class as identifier, the public boolean equals(Object obj) method of the identifier class should be overridden to perform an efficient comparison of identifier instances. The public int hashcode() method should also be overridden and must be consistent with the public boolean equals(Object obj) implementation.
*An identifier generator can be used to generate the object identifiers in a consistent manner. A predefined identifier generator is available in ilog.cpl.util. IlpIDGenerator.
Note that once the proper implementation for the IlpTypeConverter is created (normally you do this by subclassing IlpDefaultTypeConverter), you can register it with the IlpContext implementation as follows:
 
IlpContext context = ...;
context.addService(IlpTypeConverter.class, new CustomTypeConverter(context));
For more information about how to customize and extend the behavior of the default type converter, refer to Type converter and to Complex types.
The IlpObject interface has methods to:
*Retrieve the object identifier
*Retrieve the corresponding business class
*Set/get the attribute values, retrieve the attribute group and notify interested listeners, according to the interface IlpAttributeHolder
JViews TGO provides the following convenience implementations of this interface that you can use directly when building your application:
*IlpDefaultObject—Default object instance created given a class and an identifier.
*IlpBeansObject—Provides a wrapper for an existing JavaBean™ instance, which will allow it to be handled as a dynamic object.
*IlpObjectSupport—Provides a default implementation for all IlpObject methods. If your Java classes do not follow the JavaBeans pattern and you cannot create your business objects by inheriting from IlpDefaultObject, you can write your own implementation of the IlpObject interface by using the class IlpObjectSupport.
Attribute API
Attributes are the properties that qualify a business class. For example, an object of type alarm can be qualified by a severity and a description. An attribute is identified by its name and its value and is typed by a Java™ class.
The following figure illustrates the attribute API:
The attribute API
The interface IlpAttribute defines attributes. It provides the following methods:
*String getName() returns the attribute name used as an identifier.
*Object getValueClass() returns the class of the attribute value.
*Object getDefaultValue() returns the default value of the given attribute. The default value is used to initialize the attribute in a newly created business object (see newInstance).
*getAttributeGroup getAttributeIlpAttribute.getAttributeGroup() returns the attribute group that contains the attribute instance.
*void setAttributeGroup(IlpAttributeGroup group) sets the attribute group that contains the instance.
*boolean isTransient() returns whether the attribute should persist or not when the business object is stored.
JViews TGO provides a set of convenience implementations for IlpAttribute that you can use directly or subclass in order to obtain application-specific behavior:
*IlpDefaultAttribute—Defines a simple attribute with a name and a value class. The attribute value is not stored in the attribute, but in the object to which this attribute belongs.
*IlpStaticAttribute—Defines an attribute with a static value; in other words, this attribute is the same for all objects that contain it.
*IlpReferenceAttribute—Defines an attribute with a value derived from the value of another attribute in the same object instance.
*IlpObjectReferenceAttribute—Defines an attribute with a value derived from the value of another attribute in another object instance.
*IlpComputedAttribute—Defines an attribute with a value that is calculated from a given formula defined by the user. For more information, see Computed attributes.
*IlpBeansAttribute—Provides a wrapper for an existing JavaBean™ class property; this wrapper makes it possible to access the property (through introspection) as if it were a dynamic attribute.
Attribute group
Attributes are logically gathered in attribute groups. An attribute group can be static or dynamic. Static attribute groups are defined by the interface IlpAttributeGroup and dynamic attribute groups are defined by IlpMutableAttributeGroup.
These interfaces provide methods that allow you to perform the following operations:
*Iterate over the list of attributes
*Search for a certain attribute given its name
*Verify whether a given attribute is present in the attribute group
*Insert and remove attributes
*Notify interested objects about the modifications described above
JViews TGO provides the following convenience implementations of IlpAttributeGroup :
*IlpDefaultAttributeGroup—Defines a simple dynamic attribute group.
*IlpExtendedAttributeGroup—Defines a dynamic attribute group that can be extended with other attribute groups. The attribute groups used are not copied, but simply referred to.
Attribute value holder
In JViews TGO, an attribute value is not carried by the attribute itself but by an attribute value holder because this value is specific to the object with which the attribute is associated. An attribute value holder is defined by the IlpAttributeValueHolder interface. Business objects and representation objects carry attribute values, and as such they implement this interface. The IlpAttributeValueHolder interface includes methods to retrieve and set the value of an attribute, and notify interested objects about changes in attribute values.
Attribute values may be set using the following method:
 
public void setAttributeValue (IlpAttribute attribute, Object value)
where value may be null.
In cases where attributes have not been set or initialized, the value is IlpAttributeValueHolder.VALUE_NOT_SET.
Attribute values may be retrieved using the following method:
 
public Object getAttributeValue (IlpAttribute attribute)
Computed attributes
A computed attribute is an attribute which value is derived from the value of one or more other attributes. To implement a computed attribute, you need to extend the abstract class IlpComputedAttribute and implement its abstract part and a constructor. The abstract part of this class is also known as the IlpAttributeValueProvider interface.
The IlpAttributeValueProvider interface contains the following methods:
 
public Object getValue (IlpAttributeValueHolder h);
public boolean isDependentOn (IlpAttribute a) ;
The getValue method returns a value that is computed from its attribute value holder parameter. The isDependentOn method specifies the attributes used to calculate the value of the computed attribute. Whenever the value of one of these attributes changes, the object carrying this attribute notifies its listeners that the computed attribute value has been modified. Note that the computed value is cached. Therefore, calling the getAttributeValue() method of IlpAttributeValueHolder twice calls the method IlpComputedAttribute. IlpComputedAttribute only once. This cached value is erased whenever the value of an attribute on which the computed attribute depends is modified.
The example below shows how to define a computed attribute that returns a sorted array of integers calculated from another array of integers.
How to define a computed attribute
 
class SortIntAttribute extends IlpComputedAttribute {
    IlpAttribute arrayAttribute;
    public SortIntAttribute(String name,
      IlpAttributeGroup model,
      IlpAttribute arrayAttribute) {
      super(name, model, arrayAttribute.getValueClass());
      this.arrayAttribute = arrayAttribute;
    }
 
    public Object getValue(IlpAttributeValueHolder h) {
      Object value = h.getAttributeValue(arrayAttribute);
      if (value != IlpAttributeValueHolder.VALUE_NOT_SET) {
        int[] array = (int [])h.getAttributeValue(arrayAttribute);
        array = (int [])array.clone();
        Arrays. sort(array);
        return array;
      }
      return IlpAttributeValueHolder.VALUE_NOT_SET;
    }
 
    public boolean isDependentOn (IlpAttribute a) {
      return a == arrayAttribute;
    }
}
The constructor of SortIntAttributes takes three arguments:
*name is the name of the attribute,
*model specifies the attribute group (usually, an IlpClass ),
*arrayAttribute specifies the attribute that the computed attribute depends on.
The constructor of the abstract class IlpComputedAttribute takes three arguments: the name, the model, and the Java class of the value it returns. If the last argument is set to null, the computed attribute returns java.lang.Object. In this example, this argument is specified and corresponds to the value class of the attribute on which the computed attribute depends.
The getValue method computes the attribute value. Computation is protected. As a consequence, if the value of the attribute on which the computed attribute depends is not initialized, or in other words if its value is IlpAttributeValueHolder, the method does not perform the computation and returns IlpAttributeValueHolder.VALUE_NOT_SET. In this example, when the value is set, the returned array is duplicated, sorted, and returned.
The implementation of the isDependentOn method is quite straightforward, since in this example the computed attribute depends only on one other attribute, which is specified in the constructor.

Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.