test

Sun GlassFish Mobility Platform 1.1 Developer's Guide for Enterprise Connectors

Chapter 5 Classes and Methods in the Enterprise Connector Business Object API Package

The Enterprise Connector Business Object (ECBO) API contains one package, com.sun.mep.connector.api, that developers must use. This chapter summarizes the classes contained within this package:

The API documentation is included in the Sun GlassFish Mobility Platform client bundle. In the directory where you unzipped the client bundle (see the Sun GlassFish Mobility Platform 1.1 Installation Guide for details), it is in the directory sgmp-client-1_1_01-fcs-b02/doc/ecbo/api.

The BusinessObject Class

Table 5–1 lists the constructor and methods belonging to the BusinessObject class, the base class for all business objects. Business objects are the entities synchronized with client applications. Each business object instance is identified by a name, which is also used to name the file that holds the object on the mobile client. Business objects are created by business object providers; see The BusinessObjectProvider Class for details.

Table 5–1 Class com.sun.mep.connector.api.BusinessObject

Method 

Description 

BusinessObject(T bobjectProvider)

Constructor that takes the BusinessObjectProvider for the business object as its argument.

public abstract void deserialize(byte[] data)

Deserializes a business object from a byte array. 

public T getBusinessObjectProvider()

Returns a reference to the business object provider associated with this object. 

public abstract <T extends BusinessObject> DeleteCommand<T> getDeleteCommand()

Returns a command that when executed can delete this business object from a back end. 

public abstract java.lang.String getExtension()

Returns the default extension for business objects of this type. Extensions are used by the files holding these objects and must be part of the contract with clients. That is, clients and connectors must use the same extension for the same type of business object. Concrete subclasses should redefine this method. 

public abstract <T extends BusinessObject> InsertCommand<T> getInsertCommand()

Returns a command that when executed can insert this business object into a back end. 

public long getLastModified()

Returns a timestamp indicating the last time this business object was modified. The timestamp represents the number of milliseconds since “the epoch,” namely January 1, 1970, 00:00:00 GMT. 

public java.lang.String getName()

Returns the name of this business object. Names must be unique identifiers. 

public abstract <T extends BusinessObject> UpdateCommand<T> getUpdateCommand()

Returns a command that when executed can update this business object in a back end. 

public boolean hasLastModified()

Returns a flag indicating if the lastModified timestamp is supported by this connector. The Gateway will always prefer timestamps over digests to detect updates, if available.

public abstract byte[] serialize()

Serializes a business object into a byte array. 

public void setLastModified(long millis)

Sets a timestamp indicating the last time this business object was modified. The timestamp must represent the number of milliseconds since “the epoch,” namely January 1, 1970, 00:00:00 GMT. 

public void setName(java.lang.String name)

Sets the name of this business object. Names must be unique identifiers. 

The BusinessObjectProvider Class

Table 5–2 lists the constructor and methods belonging to the BusinessObjectProvider class. This provider class for instances of BusinessObject serves multiple purposes:

An instance of this class is created for each synchronization session. Use the methods initialize() and terminate() to allocate and free session resources.

Table 5–2 Class com.sun.mep.connector.api.BusinessObjectProvider

Method 

Description 

public BusinessObjectProvider()

No-argument constructor. 

public abstract java.util.List<T> getBusinessObjects()

Returns a complete list of the business objects available in the back end associated with this provider. This is in essence a query method for all the instances in the back end. 

public abstract java.lang.String getRepositoryName()

Returns the name of the repository holding these objects. 

public SessionContext getSessionContext()

Returns the session context associated with this provider. 

public <U extends BusinessObjectProvider> TransactionManager<U> getTransactionManager()

Returns the transaction manager associated with this provider, or null if no transaction manager has been set. If null is returned, transactions are not supported by this provider. 

public void initialize()

This method is called right after an instance of this class is created. You can use it to allocate resources for the duration of a synchronization session. Other uses of this method include back-end authentication. Credentials needed for authentication are available from the SessionContext, which you can access by calling getSessionContext().

public void mergeBusinessObjects(T serverObject, T clientObject)

This method is called to resolve an update conflict. A connector is responsible for merging serverObject and clientObject and returning the result in serverObject. Calling getLastModified() may be helpful during the implementation of this method.

public abstract T newBusinessObject()

Returns a fresh instance of a business object. 

public void setSessionContext(SessionContext context)

Sets the session context for this provider. 

public void terminate()

This method is called when a synchronization session is about to be terminated. Use this method to free any resources allocated by this object. 

The Command Class

Table 5–3 lists the constructor and methods belonging to the Commandclass. This class is the base class for all business object commands. The classes that extend this class are described in The DeleteCommand Class, The InsertCommand Class, and The UpdateCommand Class.

Table 5–3 Class com.sun.mep.connector.api.Command

Method 

Description 

public Command(T bobject)

Constructor that takes a business object argument. 

public abstract void execute()

Executes this command against a back end. Unchecked exceptions, such as java.lang.RuntimeException, can be used to report errors.

public T getBusinessObject()

Returns the business object on which this command is executed. 

The DeleteCommand Class

Table 5–4 lists the constructor and method belonging to the DeleteCommand class. This class is the base class for delete business object commands. It deletes a business object from a back end.

Table 5–4 Class com.sun.mep.connector.api.DeleteCommand

Method 

Description 

public DeleteCommand(T bobject)

Constructor that takes a business object argument. 

public abstract void execute()

Executes this command against a back end. Unchecked exceptions, such as java.lang.RuntimeException, can be used to report errors.

The InsertCommand Class

Table 5–5 lists the constructor and method belonging to the InsertCommand class. This class is the base class for insert business object commands. It inserts a business object into a back-end.

Table 5–5 Class com.sun.mep.connector.api.InsertCommand

Method 

Description 

public InsertCommand(T bobject)

Constructor that takes a business object argument. 

public abstract void execute()

Executes this command against a back end. Unchecked exceptions, such as java.lang.RuntimeException, can be used to report errors.

The SessionContext Class

Table 5–6 lists the constructor and methods belonging to the SessionContext class. This class stores contextual information about the session in which a BusinessObjectProvider is instantiated. This information includes credentials for logging into an EIS/EAI system or a database as well as well as properties associated with an Enterprise Connector.

Table 5–6 Class com.sun.mep.connector.api.SessionContext

Method 

Description 

public SessionContext(java.lang.String username, java.lang.String password)

Two-argument constructor that accepts username and password credentials. 

public java.util.Map<java.lang.String, java.lang.String> getParameters()

Returns all properties specified in the Admin Console's definition for this Enterprise Connector. 

public java.lang.String getPassword()

Returns the password used to log into the Enterprise Connector. 

public java.lang.String getUsername()

Returns the user name used to log into the Enterprise Connector. 

public void setParameter(java.lang.String name, java.lang.String value)

Stores a name and value pair in the internal map. 

The TransactionManager Class

Table 5–7 lists the constructor and methods belonging to the TransactionManager class. This class provides the transaction manager for a business object provider class. It supports methods for starting, stopping, and aborting back-end transactions.

Table 5–7 Class com.sun.mep.connector.api.TransactionManager

Method 

Description 

public TransactionManager(T bobjectProvider)

Constructor that creates a new TransactionManager for the specified business object provider.

public void abortTransaction()

Rolls back the current transaction on the back-end system. By default, this operation is a no-op. 

public void beginTransaction()

Starts a new transaction on the back-end system. All business object updates, deletes and inserts will be executed in a transaction. By default, this operation is a no-op. 

public void endTransaction()

Ends the current transaction on the back-end system. All business object updates, deletes and inserts will be executed in a transaction. By default, this operation is a no-op. 

public T getBusinessObjectProvider()

Returns the business object manager associated with this transaction manager. 

The UpdateCommand Class

Table 5–8 lists the constructor and method belonging to the UpdateCommand class. This class is the base class for update business object commands. It updates a business object in a back end.

Table 5–8 Class com.sun.mep.connector.api.UpdateCommand

Method 

Description 

public UpdateCommand(T bobject)

Constructor that takes a business object argument. 

public abstract void execute()

Executes this command against a back end. Unchecked exceptions, such as java.lang.RuntimeException, can be used to report errors.