com.netscape.pm.model
Interface IDataElement

All Superinterfaces:

IPMElement

All Known Implementing Classes:

BasicCustomField

public interface IDataElement

extends IPMElement

Defines an object that will implement the data management logic for a data field. The data management component is responsible for:

• initializing the field with its default value upon creation, and
• handling the storage and loading of the data to a persistent resource.

The persistence contract between the custom field and the Process Manager engine is defined as a part of the IDataElement interface. Unlike the behavior displayed in NPM 1.x, the Process Manager engine does not handle the loading and storage needs of the field. When the process instance is ready to store itself to the cluster's database, the engine will sequentially iterate through each of the custom fields defined in the application and call their store method. Similarly, when the process instance has been requested to load itself, each custom field will be called to load their data values from whatever external resource they are bound to.

Currently, global transactions are not supported in PM 6.0. It is possible for your custom fields to be accessing resources that are XA compliant, however the Process Manager engine cannot be involved in the transaction.

See Also:

IDataDictionary, IPresentationElement, IProcessInstance

Field Summary

static java.lang.String	NOT_YET_LOADED Custom field marker for empty data element.
static int	TYPE_BOOLEAN Storage type value for a data element that contains a boolean value.
static int	TYPE_DATE Storage type value for a data element that contains a date value.
static int	TYPE_DATETIME Storage type value for a data element that contains a date value.
static int	TYPE_ENTITY Storage type value for a custom field.
static int	TYPE_FLOAT Storage type value for a data element that contains a floating-point value.
static int	TYPE_INT Storage type value for a data element that contains an integer value.
static int	TYPE_LONGTEXT Storage type value for a data element that contains textual data.
static int	TYPE_TEXT Storage type value for a data element that contains textual data.
static int	TYPE_UNDEFINED Data element storage type value for an undefined type.

Method Summary

void	archive(IProcessInstance pi, java.io.OutputStream os) Writes out the data associated with the custom field to an output stream.
boolean	canSearch() Returns true if this field is searchable from the Express search page.
void	create(IProcessInstance pi) Initializes a newly created process instance with a default value for the custom field.
java.lang.Object	getDefaultValue() Returns the default value of the data element (set by the process designer at design time)
IPresentationElement	getPresentationElement() Get access to the presentation side of the field.
int	getSize() Returns the size of the storage type of the data element.
int	getType() Returns the storage type of the data element.
void	load(IProcessInstance pi) Loads the data associated with the custom field from a persistent resource.
void	store(IProcessInstance pi) Stores the data associated with the custom field to a persistent resource.

Methods inherited from interface com.netscape.pm.model.IPMElement

dumpState, getDescription, getName, getParent, getPrettyName, getProperty, isLocked, lockObject, postCreation, setParent, setProperties, toString

Field Detail

TYPE_UNDEFINED

public static final int TYPE_UNDEFINED

Data element storage type value for an undefined type. A data element should never have its storage type set to this value; this value is used to indicate an error state in a data element.

See Also:

getType()

Since:

NPM 1.0

TYPE_TEXT

public static final int TYPE_TEXT

Storage type value for a data element that contains textual data. Data elements that have this data type will store their data as:

• VARCHAR2 in Oracle
• VARCHAR in Sybase

See Also:

getType()

Since:

NPM 1.0

TYPE_LONGTEXT

public static final int TYPE_LONGTEXT

Storage type value for a data element that contains textual data. Data elements that have this data type will store their data as:

• VARCHAR2 in Oracle
• TEXT in Sybase

See Also:

getType()

Since:

NPM 1.0

TYPE_DATE

public static final int TYPE_DATE

Storage type value for a data element that contains a date value. Data elements that have this data type will store their data as:

• DATE in Oracle
• DATETIME in Sybase

See Also:

getType()

Since:

NPM 1.0

TYPE_DATETIME

public static final int TYPE_DATETIME

Storage type value for a data element that contains a date value. Data elements that have this data type will store their data as:

• DATE in Oracle
• DATETIME in Sybase

See Also:

getType()

Since:

NPM 1.0

TYPE_BOOLEAN

public static final int TYPE_BOOLEAN

Storage type value for a data element that contains a boolean value. Data elements that have this data type will store their data as:

• CHAR in Oracle
• CHAR in Sybase

See Also:

getType()

Since:

NPM 1.0

TYPE_FLOAT

public static final int TYPE_FLOAT

Storage type value for a data element that contains a floating-point value. Data elements that have this data type will store their data as:

• NUMBER in Oracle
• DOUBLE in Sybase

See Also:

getType()

Since:

NPM 1.0

TYPE_INT

public static final int TYPE_INT

Storage type value for a data element that contains an integer value. Data elements that have this data type will store their data as:

• INTEGER in Oracle
• INTEGER in Sybase

See Also:

getType()

Since:

NPM 1.0

TYPE_ENTITY

public static final int TYPE_ENTITY

Storage type value for a custom field. Custom fields should always have their data type value set to this value or the Process Manager engine will not properly detect that the custom field class store method should be called.

See Also:

getType()

Since:

NPM 1.0

NOT_YET_LOADED

public static final java.lang.String NOT_YET_LOADED

Custom field marker for empty data element. This value is used by the Process Manager engine to mark a custom field as being loaded yet. When the getData method is called from the IProcessInstance interface, the custom field's load method will be invoked if the current data value for the field is NOT_YET_LOADED. Users will never see this value being returned via getData.

See Also:

IProcessInstance.getData(java.lang.String)

Since:

PAE 4.0

Method Detail

getType

public int getType()

Returns the storage type of the data element. This value indicates how the field will store its data value.

Since:

NPM 1.0

See Also:

TYPE_UNDEFINED, TYPE_TEXT, TYPE_LONGTEXT, TYPE_DATE, TYPE_DATETIME, TYPE_BOOLEAN, TYPE_FLOAT, TYPE_INT, TYPE_ENTITY

getSize

public int getSize()

Returns the size of the storage type of the data element. This value is used by the Process Manager Administrator during application deployment to create a database column of the appropriate size. For instance, if this field had type TYPE_TEXT with size 100, the resulting database column would have type VARCHAR( 100 ) on a Sybase system.

Designers of custom fields are responsible for creating the necessary storage themselves, hence this method is may return any arbitrary value for fields of that type.

Since:

NPM 1.0

See Also:

getType()

getDefaultValue

public java.lang.Object getDefaultValue()

Returns the default value of the data element (set by the process designer at design time)

Since:

iPM6.5

create

public void create(IProcessInstance pi)
            throws java.lang.Exception

Initializes a newly created process instance with a default value for the custom field. Most of the time, this method will create a default value and store it in the process instance via the setData method. This is not required for all custom fields and will depend upon the designer's discretion. In fact, if you really do not need to set a default value, it is best to skip implementing create and leave it blank; the store method for custom fields is called only when a setData call has been performed on the field.

The create method for all fields, built-in or custom, will be called when the user initiates a process instance from the entry point.

In the event that your create call fails, you can throw a java.lang.Exception at any time to signal an error. An error message will be displayed to the user and the process instance will not be created.

Parameters:

pi - the current process instance

Throws:

java.lang.Exception - if there is a problem initializing the field's default value.

Since:

PAE 4.0

See Also:

IProcessInstance

store

public void store(IProcessInstance pi)
           throws java.lang.Exception

Stores the data associated with the custom field to a persistent resource. The choice for an external persistent datastore will depend on the field designer, however it is not possible to store the field data in the application specific table where the built-in data fields serialize themselves. The responsibility for storing the data lies with the custom field, the responsibility for storing the custom field's primary key lies with the Process Manager engine - the key is stored in the application specific database table.

Currently, the Process Manager engine does not support global transactions. If the external datasource your custom field serializes to is XA compliant and managed by a resource manager, your custom field could participate in a global transaction, however the transactions initiated by the Process Manager engine are not made through an XA resource manager and cannot be a part of the larger transaction.

In the event that your store call fails, you can throw a java.lang.Exception at any time to signal an error. The current workitem is converted to an exception workitem and all the data field values are reset to their values prior to the request.

The store method is only called if the field's value has been modified. This is covered in further detail below in a brief discussion of lazy loading.

What is Lazy loading?

The custom field's load method is only invoked if and only if there is a request to fetch the field's data value via the getData method from the process instance. When the process instance is loaded, all of the built-in data elements have their data values loaded into the process instance since their values come from the application specific table in the cluster database. The custom fields store their data in systems external to the engine; loading the data associated with a custom field could be quite expensive, and is not even necessary if the value is not used during the life of the request.

The storage of the custom field's data is also done lazily. The store method is only called if the data value has been changed via the setData method on the process instance. Since the load method on the custom field usually performs a call to setData, we have a side effect where store will be called if load has been called. The custom field's primary key, however is always available once the process instance has been loaded.

Parameters:

pi - the current process instance

Throws:

java.lang.Exception - if there is a problem storing the field's data value to the back-end storage.

Since:

PAE 4.0

See Also:

IProcessInstance.getData(java.lang.String), IProcessInstance.setData(java.lang.String, java.lang.Object)

load

public void load(IProcessInstance pi)
          throws java.lang.Exception

Loads the data associated with the custom field from a persistent resource. The data object associated with the custom field is opaque to the Process Manager engine. Any user scripts that access and modify the data associated with the field must implicitly know what type the data object conforms to. To use a shopping cart as an example, suppose we have defined the object:

ShoppingCartField

the custom field class.

ItemSet

the data element that the custom field will be manipulating.

Item

a helper class; an ItemSet is a container for a series of Item objects.

Using this example, any scripts that access the shopping cart field will need to know the API for the ItemSet and Item objects.

The load method is invoked whenever the data value associated with the custom field is accessed via the getData method off the process instance. The built-in fields are loaded whenever the process instance is loaded, but custom fields are only loaded when their data value is explicitly asked for. Since load is invoked whenever a getData is performed, it is very very very important that you do not do a getData on the custom field inside of your load method. This will result in an infinite loopand obliterate any chances of you and your system administrator becoming friends.

In the event that your load call fails, you can throw a java.lang.Exception at any time to signal an error. If the current action is to display a form, an error message will be displayed to the user. If the user has completed a workitem, an exception workitem will be created.

Parameters:

pi - the current process instance

Throws:

java.lang.Exception - if there is a problem retrieving the field's data value to the back-end storage.

Since:

PAE 4.0

See Also:

store(com.netscape.pm.model.IProcessInstance), IProcessInstance.getData(java.lang.String)

archive

public void archive(IProcessInstance pi,
                    java.io.OutputStream os)
             throws java.lang.Exception

Writes out the data associated with the custom field to an output stream. When an archive operation is initiated from the administration pages, all of the data elements associated with the process instance must write their data values out to an output stream. The built-in data elements archive themselves by simply writing their values out as bytes. The manner in which your custom field writes its data to the output stream is up to you; you can stream bytes or encapsulate the values in XML.

In the event that your archive call fails, you can throw a java.lang.Exception at any time to signal an error. An error message will be displayed to the administrator.

Parameters:

pi - the current process instance

os - the output stream to archive the data element to

Throws:

java.lang.Exception - if there is a problem archiving the field's data value to the output stream.

Since:

PAE 4.0

See Also:

#IProcessInstance#archive

canSearch

public boolean canSearch()

Returns true if this field is searchable from the Express search page. If a built-in field has been marked as searchable, its data value can be searched upon from the Express UI.

As of PM 6.0, a search framework for custom fields has not yet been written. Custom fields may return either true or false from this method.

Returns:

true if this field is searchable from the Express; false otherwise.

Since:

PAE 4.0

getPresentationElement

public IPresentationElement getPresentationElement()

Get access to the presentation side of the field. Field designers may choose to implement their custom field in two separate components: one for the presentation logic and another for the data management logic. This method should be used to return access to the presentation portion of the field. It is not necessary to implement your custom field in this manner however, one class may contain both the data management and presentation logic.

Returns:

the handle to the presentation element manager of the field.

Since:

PAE 4.0

See Also:

IPresentationElement