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.