com.baan.b3.boi1
Class BusinessObjectManager

java.lang.Object
  |
  +--com.baan.b3.boi1.BusinessObjectManager

public abstract class BusinessObjectManager

extends java.lang.Object

Base class for type-safe interfaces to backends.
Subclasses can query a backend for specific types of business object. Changes can be made on the resultant data set and subsequently synchronized with the backend. Business objects can also be inserted or deleted.
This class is also used as a superclass for type-safe access to APIs in the backend through a remote function call mechanism

Version:

Build Nr 61, file version \\main\\6, 15:08:55 24-07-2006 UTC

Field Summary

static java.lang.String	BDC_METHOD_ADAPTER_CLASS_NAME
static java.lang.String	BSQ_METHOD_ADAPTER_CLASS_NAME
static java.lang.String	QBD_METHOD_ADAPTER_CLASS_NAME

Method Summary

void	add(BusinessObject p_object) Adds a 'new' business object to the control of this manager.
void	changeBusinessObject(BusinessObject p_oldValue, BusinessObject p_newValue) Instructs the manager to change a business object.
void	close() Closes a manager, closes the connection with it's OpenWorldX Adapter backend and frees up it resources.
java.lang.String	getCurrentBackend() Retrieves the identifier for the current backend.
Iterator	getIterator() Returns an Iterator after making some 'Combined calls'.
long	getTimeOut() Returns the timeout currently set on this manager.
IExceptionDescriptor[]	getWarnings() Retrieves all warnings that have occurred since the last call to this method.
void	initialize(java.lang.String p_backendComponentName) Initializes this manager for a specific OpenWorldX Adapter backend.
void	introduce(BusinessObject p_object) Introduces an object into this manager.
void	ping() Pings connected backend.
void	release(BusinessObject p_businessObject) Release one particular business object from this manager.
void	releaseAll() Releases all the business objects this manager keeps in 'memory'.
void	remove(BusinessObject p_businessObject) Earmarks a local business object for removal.
void	setTimeOut(long p_timeout) Changes the time this manager waits for the result.
void	setTransactionScope(TransactionScope p_transactionScope) Sets the transaction scope for this manager The default is TransactionScope.NONE Postconditions: The transaction scope of this manager is set to the value specified by p_transactionScope Threading policy: Unsafe
void	setUnconditional(boolean p_unconditional) Sets the unconditional feature for this manager.
void	setUserInfo(IUserInfo p_userInfo) Sets the user context for this manager Postconditions: The manager uses the specified user context Threading policy: Unsafe
void	synchronize() Synchronizes local changed business objects to the backend.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BSQ_METHOD_ADAPTER_CLASS_NAME

public static final java.lang.String BSQ_METHOD_ADAPTER_CLASS_NAME

BDC_METHOD_ADAPTER_CLASS_NAME

public static final java.lang.String BDC_METHOD_ADAPTER_CLASS_NAME

QBD_METHOD_ADAPTER_CLASS_NAME

public static final java.lang.String QBD_METHOD_ADAPTER_CLASS_NAME

Method Detail

getIterator

public Iterator getIterator()
                     throws java.lang.IllegalStateException

Returns an Iterator after making some 'Combined calls'.
After performing some calls to this manager with the 'combining call' functionality (the add methods on the type-safe subclass), this method returns the iterator which contains all the requested data
Preconditions: One or more calls to an add method should have been performed previously
Postconditions: The returned iterator is ready to loop trough the data
Threading policy: Unsafe

Returns:

the requested data (shall not be null)

Throws:

java.lang.IllegalStateException - if the preconditions are not met

initialize

public void initialize(java.lang.String p_backendComponentName)
                throws BoiException

Initializes this manager for a specific OpenWorldX Adapter backend.
The manager is initialized and links to a specific OpenWorldX Adapter backend. The backend is refered to by a bus component. Calling this method opens an connection between 'this' client and the server.
Preconditions: Depending on the transport layer, certain preconditions may need to be met. For instance, in the case of the socket transport layer the OpenWorldX Adapter backend needs to have been started
Postconditions: The connection to the server is opened, the manager is ready to be used.
Threading policy: Unsafe

Parameters:

p_backendComponentName - the name of the bus component that refers the backend (must not be null or have length 0)

Throws:

BoiException - if something went wrong at the adapter or at the transport level

ping

public void ping()
          throws BoiException

Pings connected backend.
This method can be used to ping the backend belonging to this initialized Manager. In this wat his method differs from the BackendControl ping method.
Throws Exception if something goed wrong.
Resets backend server timeout.
Threading policy: Unsafe

Throws:

BoiException - if something went wrong at the adapter or transport level

synchronize

public void synchronize()
                 throws BoiException,
                        BoiSynchronizationException

Synchronizes local changed business objects to the backend.
This method is part of the Data Oriented Programming model, and can be used to add, change or remove data from the backend (DB).
Preconditions: Changed, added, or removed business objects need to be linked to the manager
Postconditions: The backend is updated to correspond with the state of the local business objects. The state of the local business objects is undefined
Threading policy: Unsafe

Throws:

BoiException - if something went wrong at the adapter or transport level

BoiSynchronizationException - if something went wrong at the 'server' application level

setTimeOut

public void setTimeOut(long p_timeout)

Changes the time this manager waits for the result.
The timeout is the time the manager waits for the result from the OpenWorldX Adapter backend. When there is no reply within the timeout, a BoiException is thrown. This mechanism is to prevent client applications from 'hanging' because of non responding OpenWorldX Adapter servers
Postconditions: The timeout is changed
Threading policy: Unsafe

Parameters:

p_timeout - the timeout in milliseconds to set on the manager, 0 = no timeout; wait forever (must not be less than 0)

getTimeOut

public long getTimeOut()

Returns the timeout currently set on this manager.
Threading policy: Unsafe

Returns:

the timeout that is set on this manager, 0 = no timeout, wait forever (shall not be less than 0)

See Also:

setTimeOut(long)

add

public void add(BusinessObject p_object)

Adds a 'new' business object to the control of this manager.
With this method 'new' records can be added to the database
Postconditions: The business object is linked to the manager
Threading policy: Unsafe

Parameters:

p_object - the 'new' business object to link to this manager (must not be null)

introduce

public void introduce(BusinessObject p_object)

Introduces an object into this manager.
The manager will then keep track of links to other BusinessObjects. This method should only be used during the preparation of arguments for the changeBusinessObject(com.baan.b3.boi1.BusinessObject, com.baan.b3.boi1.BusinessObject) function.
Threading policy: Unsafe

Parameters:

p_object - the BusinessObject that this manager needs to track (must not be null)

close

public void close()

Closes a manager, closes the connection with it's OpenWorldX Adapter backend and frees up it resources.
Closes the connection between this manager and the OpenWorldX Adapter backend, the actual functionality of closing a connection depends on the transport layer used.
Postconditions: The manager holds no more resources and can be reused.
Threading policy: Unsafe

releaseAll

public void releaseAll()

Releases all the business objects this manager keeps in 'memory'.
This function releases all the business objects of which the manager tracks the changes.
Postconditions: A call to synchronize() will no longer result in a change in the backend
Threading policy: Unsafe

release

public void release(BusinessObject p_businessObject)

Release one particular business object from this manager.
This function releases a business object of which the the manager tracks the changes.
Postconditions: Any changes made to the business object will not be sent to the backend with the next synchronize() call. Nor will the object be added or removed in the cases where add(com.baan.b3.boi1.BusinessObject) or remove(com.baan.b3.boi1.BusinessObject) were called, respectively
Threading policy: Unsafe

Parameters:

p_businessObject - the business object to be release (must not be null)

remove

public void remove(BusinessObject p_businessObject)

Earmarks a local business object for removal.
With the next synchronize() on this manager, the request for removing the business object from the backend is send to the server
Postconditions: This manager recognises that the business object should be removed
Threading policy: Unsafe

Parameters:

p_businessObject - the business object to be removed from the backend (must not be null)

getWarnings

public IExceptionDescriptor[] getWarnings()

Retrieves all warnings that have occurred since the last call to this method.
Postconditions: A subsequenct call to this method will return an empty array
Threading policy: Unsafe

Returns:

an array of objects that describe warning events (shall not be null, may have length 0)

setTransactionScope

public void setTransactionScope(TransactionScope p_transactionScope)

Sets the transaction scope for this manager
The default is TransactionScope.NONE
Postconditions: The transaction scope of this manager is set to the value specified by p_transactionScope
Threading policy: Unsafe

Parameters:

p_transactionScope - an integer constant that indicates which transactionscope to use (must be TransactionScope.NONE, TransactionScope.GLOBAL, TransactionScope.MANAGER or TransactionScope.BUSINESSOBJECT)

setUserInfo

public void setUserInfo(IUserInfo p_userInfo)

Sets the user context for this manager
Postconditions: The manager uses the specified user context
Threading policy: Unsafe

Parameters:

p_userInfo - the userinfo object to use with this manager (must not be null)

setUnconditional

public void setUnconditional(boolean p_unconditional)

Sets the unconditional feature for this manager.
With this feature turned on, the optimistic locking mechanism is disabled. The consistency rules of the backend are, however, still in place.
Postconditions: The unconditional feature is turned on or off for this manager depending on the value p_unconditional
Threading policy: Unsafe

Parameters:

p_unconditional - true to turn of the unconditional feature, false to turn it off

changeBusinessObject

public void changeBusinessObject(BusinessObject p_oldValue,
                                 BusinessObject p_newValue)
                          throws java.lang.IllegalArgumentException,
                                 BoiProgrammingRException

Instructs the manager to change a business object.
This method tells the manager to change a business object from a specified old state to a specified new state. There are restrictions to the types of change that are allowed. Consider that a business object is in fact a tree of business objects (a business objects has business object members which can also have members etc...).

• The old and new business object state trees must not be cyclical in any way (ie. a child that points to an ancestor)
• Any vector member in the business object tree can only have undergone one of the following three changes and not a combination of them: elements are inserted, elements are deleted or elements are changed.
• If elements were inserted into/deleted from a vector member in the business object tree, the unchanged elements should have absolutely identical values.

A null value for the old state tells the manager to insert a new element. A null value for the new state tells the manager to delete the element.
Preconditions: p_oldValue and p_newValue have valid, acyclic values. They have both been introduce(com.baan.b3.boi1.BusinessObject)d to this manager
Postconditions: This manager contains instructions to alter the state of the business object from p_oldValue to p_newValue. These instructions will be sent to the backend the next time synchronize() is called
Threading policy: Unsafe

Parameters:

p_oldValue - the old/current value of the business object. Can only be null if p_newValue is not null

p_newValue - the new/intended value of the business object. Can only be null if p_oldValue is not null

Throws:

java.lang.IllegalArgumentException - if a vector member has undergone a combined delete/insert/change operation

BoiProgrammingRException - if both arguments are null

getCurrentBackend

public java.lang.String getCurrentBackend()

Retrieves the identifier for the current backend.
The String returned by this method has the same format as the String used as an argument in the initialize(java.lang.String) function. This String can be used as an argument for the DirectoryToolkit.getBusComponent(java.lang.String) function to retrieve a IBusComponent object.
Preconditions: This manager is initialize(java.lang.String)d
Threading policy: Unsafe

Returns:

a String identifying the backend this manager is currently initialized for. Null means no backend is specified.