Note:

Extension of the classes in this package is prohibited unless otherwise documented. Similarly, extension or implementation of the interfaces in this package is prohibited except as documented.

Package com.sas.entities

Defines interfaces and classes for Entities, which are a dynamic extension of Java Beans.

See:
Description

Interface Summary

AttributeDescriptorInterface	AttributeDescriptorInterface describes an AttributeDescriptor for an Entity.
AttributeGroupInterface	AttributeGroupInterface is a collection of attributes of an Entity, including both type-based and instance-based attributes.
AttributeTypeFactoryInterface	AttributeTypeFactoryInterface describes the factory methods that can be invoked to create instances of AttributeTypeInterface.
AttributeTypeInterface	AttributeTypeInterface describes AttributeTypes which define properties that are common to AttributeDescriptors of that type.
BaseAttributeDescriptorInterface	Base AttributeDescriptorInterface defines a core API for AttributeDescriptors, AttributeGroups, and AttributeTypes.
BaseEntityInterface	BaseEntityInterface represents a local (non-remote)Entity.
BaseEntityValueInterface	BaseEntityValueInterface represents a local (non-remote)Entity.
EntityContextInterface	The EntityContextInterface interface defines the context names for entity editors, customizers, and validators.
EntityInterface	EntityInterface represents a possibly remote object Entity.
EntityKeyInterface	EntityKeyInterface provides methods for Entities that contain Globally Unique Identifiers (sometimes known as GUIDs).
RemoteBaseEntityInterface	RemoteBaseEntityInterface extends the functionality of RemoteBaseEntityValueInterface.
RemoteBaseEntityValueInterface	RemoteBaseEntityValueInterface represents a core API for accessing the attributes (name/value pairs) of an Entity.
RemoteEntityInterface	RemoteEntityInterface extends the functionality of RemoteBaseEntityInterface.

Class Summary

AggregateEntity	AggregateEntity is a collection of entities that function as a single Entity object.
AttributeDescriptor	A base implementation of AttributeDescriptorInterface.
AttributeGroup	An implementation of AttributeGroupInterface.
AttributeType	A simple implementation of AttributeTypeInterface.
AttributeTypeFactory	AttributeTypeFactory contains constants for creating AttributeTypes
BaseAttributeDescriptor	This class is a base class for AttributeDescriptor, AttributeGroup, and AttributeType.
BaseEntity	BaseEntity is an entity object that is not a remote object.
Entity	Entity, as described by EntityInterface, is a Java component which can have a dynamic or changing set of attributes, as opposed to the fixed set of properties of a Java Bean.
EntityAttr	EntityAttr is a helper class that organizes and maintains EntityInterface+AttributeDescriptor name entries for the AggregateEntity.
RemoteEntity	RemoteEntity represents a possibly-remote implementation of RemoteEntityInterface.

Exception Summary

AttributeSetException

An AttributeSetException is thrown when an assignment to an Entity's attribute fails.

Package com.sas.entities Description

Defines interfaces and classes for Entities, which are a dynamic extension of Java Beans.

Entities, as described by EntityInterface, are Java components which have a dynamic or changing set of attributes, as opposed to the fixed set of properties of a Java Bean. To assist with understanding the concept, the following terms will be used:

Terms

entity

An abstract name for a software component (object) that has a set of fixed as well as dynamic attributes. Examples of entities are reports, queries, stored procedures, Java beans, JSP custom tags, web pages, web forms, and applications.

attribute

A named, typed value associated with a (parameterized) entity. An attribute may be changed by an outside consumer of the entity. The attribute has several characteristics: name, display name, type, description, visible, modifyable, optional validation criteria such as a list of valid values, zero or one default values, and so on. (See below for details). Parameter and attribute or interchangable terms.

For example, the date for a report is a dynamic attribute. Its type is a date type (i.e. a numeric type). Its description may be a string such as "Sales report month". The default value may be an expression that yields the current month when evaluated.

parameter.

See attribute

type based attributes

attributes of an entity which are defined by the entity's type. The set of type based attributes is common to all instances of the same type or class. Type based attributes are those defined by Java Beans and the java.beans.Introspector and java.beans.BeanInfo associated with the entity class.

instance based attributes

attributes of an entity which are independent of its type. The set of instance based attributes can vary from one instance to the next, even though the two instances are of the same type. Instance based attributes are most commonly derived from the content of the entity, rather than the type of the entity.

For example, two different report instances, ActualSales and ForecastedEarnings, may both be instances of the same Report type, and thus have the same set of type based attributes However, the ActualSales report may have three parameters, Month, Year, and Region, whereas the ForecastedEarnings report may have two parameters, Sector and Year. These instance based attributes (also known as dynamic attributes) differ from instance to instance. However, we wish to be able to edit them using property sheets, validators, and customizers.

parameterize

To add the ability to change data or characteristics of an entity through a parameter substitution mechanism that is shared with other subsystems. For example, a static report may display sales figures for March, 2001. Parameterizing this report would make the date subject to change via parameterization, allowing you to use the same report definition to display the sales for April, 2001, or May, 20001, etc. by specifying a date parameter when running the report.

parameterized entity

An entity that has one or more free parameters (also known as attributes). A free parameter is one that is not bound; i.e. its value is free to change.

prototype

An entity that serves as a prototype (sample or template) from which other entities are instantiated. The instantiated entity inherits the attributes of its prototype and may bind the free attributes and define additional attributes. The new instance can also serve as a prototype for other entities.

Entity Attributes (Parameters)

Instance Based and Type Based Attributes

The system will support parameter set definition based on both the type of the component (type based attributes) and the instance (instance based attributes). This is necessary due to the template/prototype nature of the entities of interest. For example, a generalized reporting system will support an unbounded set of reports. Each report has different potential content defined when the report is built. For example, the analyst building the report may add two charts and a table and surface two attributes of each chart (date, type) and three attributes of the table as external parameters of the report template, yielding a parameterized report, MyReport, with five free parameters. In this example, they may be called chart1Date, chart1Type, chart2Date, chart2Type, tableCaption. It would be unfeasible to try to define new, unique types (i.e. Java classes, COM interfaces) to define each possible report instance. Instead, the parameterized entity subsystem will support such instance based attributes.

Prototypes

We also wish to support prototype objects. A prototype, also known as a template, is a parameterized entity (an instance of parameterized class) which has one or more of its free attributes bound. Other objects are cloned from this prototype and optionally one or more of their free parameters are bound (which makes them different from their prototype). These derived instances may themselves be prototypes for other entities. For example, the above described report prototype has five free parameters. An analyst can then bind chart1Type and chart2Type to "StackedBar" and save this as a new report prototype MyDerivedReport with only three free parameters.

This prototype relationship can take one of two flavors. A static prototype is used for instantiation only. It does not play any role after this point. Later changes to a static prototype are not reflected in any entities instantiated from it. This is like embedding in OLE/ActiveX.

A dynamic prototype is more active and probably more useful. The derived instance will maintain a dependency on its dynamic prototype such that later changes to the prototype are reflected by the derived entity, unless the derivative has explicitly bound that parameter. This is like linking in OLE/ActiveX.

For example, consider our derived parameterized report that contains three parameters:

chart1Date

the date used to create chart 1

chart2Date

the date used to create chart 2

tableCaption

caption to appear below the table

If the parameterized report MyDerivedReport uses a static prototype, MyReport then it will always display stacked bar charts, even if the base report is changed to a simple bar chart. If instead MyDerivedReport uses a dynamic prototype MyReport, then after changing the base report to a simple bar chart, viewing MyDerivedReport will also show a simple bar chart. This implies that all report prototypes in an ancestry chain must be available to render the derived report.

All entities, and thus all prototypes, will be instances of some class. For example, parameterized reports will be instances of a (as yet unspecified) report class; parameterized queries, of some abstract query type, etc. These base classes can all implement a common EntityInterface which provides the abstract ability to participate in the generalized parameterized entity framework. Each such type will have a set of type based attributes defined by that type. For example, the report class will have a title attribute, so all reports instances will have a title attribute.

Comparison to Java Beans

The Java Beans specification defines only static or type based attributes; all instances of the same class have the same set of attributes, irregardless of their content or state. Also, Java Beans does not work very well with RMI, since although the Introspector can deduce attributes from a remote object, this is based on the RMI stub which implements the remote interface and therefore does not reflect any special BeanInfo classes associated with the base type. Also, Java Beans does not support localization. The API is not localizable, so methods to get an attribute description or icon always return the information in the default locale, not the client locale. This parameterized entity API solves all of these problems.

API

The proposed API is divided into two main elements in the com.sas.entities package: the EntityInterface and the AttributeDescriptorInterface. EntityInterface defines the API for operating on an entity: getting or setting attribute values, either individually or collectively. The entity can also return the metadata that describes its attributes. Each attribute has some instance based state which describes or constrains it, as well as an attribute type, described by AttributeTypeInterface, which describes the attribute's type. The attribute type can be shared among many different attributes that have the same description, validation, editor, and customizer. An entity's collection of attributes is organized into an attribute group which is described by AttributeGroupInterface. The attribute group manages a list of related attributes as well as subgroups of other related attributes. These interfaces allow an entity to describe its instance based and type based attributes.

Note:

Extension of the classes in this package is prohibited unless otherwise documented. Similarly, extension or implementation of the interfaces in this package is prohibited except as documented.