oracle.jbo.client.remote
Class ApplicationModuleImpl

java.lang.Object
oracle.jbo.common.PropertiesHelper
oracle.jbo.client.remote.ApplicationModuleImpl

All Implemented Interfaces:

ApplicationModule, AppModuleRequestHandler, ClientComponentObject, ComponentObject, JboExceptionHandler, ObjectMarshaller, Properties, Session, SvcMsgSender, Transaction, TransPostControl, WSApplicationModuleMarshaller

public class ApplicationModuleImpl

extends PropertiesHelper

implements ClientComponentObject, ApplicationModule, TransPostControl, ObjectMarshaller, JboExceptionHandler, Transaction, Session, SvcMsgSender, WSApplicationModuleMarshaller, AppModuleRequestHandler

Abstract application module proxy. Defines the platfrom independent remote interface for concrete (platform dependent) subclasses.

Version:

INTERNAL

Field Summary

protected boolean

mRemoved

Fields inherited from class oracle.jbo.common.PropertiesHelper

mProperties

Fields inherited from interface oracle.jbo.ApplicationModule

ACTIVATE_CLIENT_FLAG, ACTIVATE_REMOVE_FLAG, ACTIVATE_SKIP_RESTORE_VO_FROM_DEF, ACTIVATE_TRANSIENT_FLAG, ACTIVATE_UNDO_FLAG, DEFAULT_DEF_FULL_NAME, DEFAULT_ROOT_APP_MOD_NAME, PASSIVATE_DEFER_FLAG, PASSIVATE_HINT_FLAG, PASSIVATE_TO_DATABASE, PASSIVATE_TO_FILE, PASSIVATE_TO_MEMORY, PASSIVATE_TO_STACK_FLAG, PASSIVATE_TRANSIENT_FLAG, PASSIVATE_UNDO_FLAG, RELEASE_LEVEL_MANAGED, RELEASE_LEVEL_RESERVED, REMOVE_SNAPSHOT, RESET_CLIENT_ONLY_FLAG, RESET_INTERNAL_FLAG, RESET_MANAGE_SNAPSHOTS, RESET_RELOAD_FLAG, RESET_ROLLBACK_FLAG, SYNC_BATCH, SYNC_IMMEDIATE, SYNC_LAZY

Fields inherited from interface oracle.jbo.common.TransPostControl

TRANS_POST_GET_ATTR_BY_INDEX, TRANS_POST_GET_ATTR_BY_NAME, TRANS_POST_GET_ATTR_COUNT, TRANS_POST_GET_ATTR_INDEX_OF, TRANS_POST_GET_STRUCTURE_DEF, TRANS_POST_PUSHBACK, TRANS_POST_REFRESH_UNDO_CHANGES, TRANS_POST_REFRESH_WITH_DB_FORGET_CHANGES, TRANS_POST_REFRESH_WITH_DB_ONLY_IF_UNCHANGED, TRANS_POST_REMOVE, TRANS_POST_SET_ATTR_BY_INDEX, TRANS_POST_SET_ATTR_BY_NAME

Fields inherited from interface oracle.jbo.Transaction

LOCK_NONE, LOCK_OPTIMISTIC, LOCK_OPTUPDATE, LOCK_PESSIMISTIC

Fields inherited from interface oracle.jbo.Session

JBO_SESSION_COOKIE, JBO_SESSION_LOCALE

Fields inherited from interface oracle.jbo.common.ws.WSApplicationModuleMarshaller

ACTIVATION_AFTER_LOSS_OF_AFFINITY, ACTIVATION_AFTER_RESTART, ACTIVATION_NONE, SYNC_INT_BATCH, SYNC_INT_BATCH_DO_WORK

Constructor Summary

ApplicationModuleImpl()

Method Summary

byte[]	activateState(int id, boolean remove)
byte[]	activateState(int id, boolean remove, SessionData info)
byte[]	activateState(int id, SessionData info, int flags) Internal: Applications should not use this method.
byte[]	activateStateForUndo(java.lang.String id, int flags) Restore an ApplicationModule undo record.
void	addClientPostListener(ClientPostListener l)
void	addResponse(java.io.Serializable res)
void	addTransactionStateListener(TransactionStateListener target) Add this TransactionListener to the list and notify all such listeners whenever commit and rollback occurs in this transaction.
void	addViewClearCacheListener(ViewClearCacheListener target)
void	addWarning(JboWarning warn) Adds a warning message.
void	afterActivation(int activationMode)
void	applyChangeSet(int id) Applies the changes committed by another transaction in order to synchronize caches between root Application Module instances.
void	beforePassivateState()
void	bindToWorkingSet(WSApplicationModuleImpl wsAM)
void	clearEntityCache(java.lang.String entityName) Clears the cache of the specified Entity Object.
void	clearVOCaches(java.lang.String entityName, boolean recurse) Clears the View Object cache for all View Objects that use an Entity Object identified by entityName.
void	closeLob(int rsId, int rowId, java.lang.String attrId, boolean forInput, boolean isCharStream)
void	commit() Execute a commit of the server to the database.
int	commitAndSaveChangeSet() Commits the transaction and writes updated EntityImpls to the persistent store.
void	connect(java.lang.String url) Make a physical connection to a database server.
void	connect(java.lang.String url, java.util.Properties info) Make a physical connection to a database server.
void	connect(java.lang.String url, java.lang.String user, java.lang.String password) Make a physical connection to a database server.
void	connectToDataSource(java.util.Hashtable initialContextEnv, java.lang.String dataSourceName, boolean isXABased) Looks up a datasource from a jndi tree and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String passwd) method.
void	connectToDataSource(java.util.Hashtable initialContextEnv, java.lang.String dataSourceName, java.lang.String user, java.lang.String passwd, boolean isXABased) Looks up a datasource from a jndi tree and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String passwd) method.
void	connectToDataSource(java.lang.String nsUrl, java.lang.String nsUser, java.lang.String nsPasswd, java.lang.String dataSourceName) Looks up a datasource from Oracle 8i namespace using the jdbc_access protocol and acquires the default jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection() method.
void	connectToDataSource(java.lang.String nsUrl, java.lang.String nsUser, java.lang.String nsPasswd, java.lang.String dataSourceName, java.lang.String user, java.lang.String password) Looks up a datasource from Oracle 8i namespace using the jdbc_access protocol and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String password) method.
ApplicationModule	createApplicationModule(java.lang.String amName, java.lang.String defName) Create a ApplicationModule using its class name and specify its name
ComponentObject	createComponentObject(java.lang.String coName, java.lang.String cDefName) Create a ComponentUsage using the name of a ComponentObject class.
protected RowSet	createDetailRowSet(int rsiId, java.lang.String rsName, java.lang.String vlDefName) Create a detail RowSet (ViewObject) using the name of a ViewObject class.
static ApplicationModuleImpl	createInstance(ResponseValues amInfo)
protected ApplicationModuleImpl	createProxyApplicationModule(ResponseValues handle)
java.lang.Object	createRef(java.lang.String structName, byte[] data) Internal: Applications should not use this method.
ViewLink	createViewLink(java.lang.String viewLinkName, java.lang.String viewLinkDefName, ViewObject master, ViewObject detail) Creates a View Link in this Application Module from the View Link definition.
ViewLink	createViewLinkBetweenViewObjects(java.lang.String viewLinkName, java.lang.String accessorName, ViewObject master, AttributeDef[] srcAttrs, ViewObject detail, AttributeDef[] destAttrs, java.lang.String assocClause) Creates a View Link in this Application Module.
ViewLink	createViewLinkFromEntityAssocName(java.lang.String viewLinkName, java.lang.String entityAssocName, ViewObject master, ViewObject detail) Creates a View Link in this Application Module from an Entity Association.
ViewObject	createViewObject(java.lang.String voName, java.lang.String vDefName) Create a ViewUsage using the name of a ViewObject class.
ViewObject	createViewObjectFromQueryClauses(java.lang.String voName, java.lang.String eoName, java.lang.String selectClause, java.lang.String fromClause, java.lang.String whereClause, java.lang.String orderByClause) Creates an View Object in this Application Module from an Entity Object and additional SQL clauses.
ViewObject	createViewObjectFromQueryStmt(java.lang.String voName, java.lang.String sqlStatement) Create a ViewUsage using a SQL statement.
ApplicationModule	createWorkerApplicationModule(java.lang.Object sessionCookie)
void	detach()
void	disconnect() Performe clean-up when client is disconnecting by dereferencing the remote instances.
void	disconnect(boolean retainState) Closes the JDBC connection object.
ServiceMessage	doMessage(ServiceMessage svcMsg)
ApplicationPoolSvcMsgContext	doPoolMessage(ApplicationPoolSvcMsgContext ctx) Internal use only.
void	doPostChanges()
java.lang.String	dumpQueryResult(java.lang.String query, java.lang.String dumpClassName, java.lang.String[] data) Writes the result of the query to a (potentially very long) string.
int	executeCommand(java.lang.String command) Executes a SQL command using a JDBC Statement under the current transaction.
void	fetchAttributeProperties(java.lang.String[] voNames, java.lang.String[][] attrNames, LocaleContext locale) Fetches all custom properties for the given list of attributes for the named ViewObjects in this application module over to the remote client objects in one network roundtrip.
ApplicationModule	findApplicationModule(java.lang.String amName) Get an ApplicationModule using its name.
ComponentObject	findComponentObject(java.lang.String coName) Finds the named Component Object.
DataCollector	findOrCreateDataCollector(java.lang.Object obj)
RowSetIterator	findRSIForEntity(RowSetIterator[] rsis, int eRowHandle) Finds the RowSetIterator associated with the specified Entity row handle.
ViewLink	findViewLink(java.lang.String viewLinkName) Finds the named View Link.
ViewObject	findViewObject(java.lang.String voName) Finds the named View Object.
ViewObject	findViewObjectUsingEntity(ViewObject[] vos, java.lang.String entityDefName, java.lang.String[] attrNames) Given an array of View Objects (the vos parameter), finds the first matching View Object.
void	finishedPiggybacking()
void	finishedProcessingPiggyback(java.lang.Exception[] exArr)
void	finishSyncWorkingSet(WSApplicationModuleImpl wsAM, boolean isEndOfSvcMsg)
java.lang.String[]	getAllApplicationModuleDefNames() Return the name of the ApplicationModule class and all the nested ApplicationModule
java.lang.String[]	getAllEntityAssociationDefNames() Gets the names of the entity association definitions defined in all packages.
java.lang.String[]	getAllEntityDefNames() Return the names of the EntityObject available in all nested packages.
java.lang.String[]	getAllViewDefNames() Return the names of the ViewObject available in all nested packages.
java.lang.String[]	getAllViewLinkDefNames() Gets the names of the View Link definitions defined in all packages.
protected ResponseValues	getAMFullRef(ResponseValues handle)
java.lang.String[]	getApplicationModuleDefNames(java.lang.String packName) Return the names of the ApplicationModule class.
java.lang.String[]	getApplicationModuleNames() Return the names of the ApplicationModules.
java.lang.String[]	getApplicationModuleNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes) Returns an array of names of the nested Application Modules in this Application Module.
AppModuleRequestHandler	getAppModuleRequestHandler()
java.lang.String	getClientProxyInterfaceName()
ConnectionMetadata	getConnectionMetadata() Returns a metdata structure that describes the transaction's JDBC connection.
WSApplicationModuleImpl	getCurrentWorkingSet()
java.lang.String	getDefFullName() Retrieve the application module definition's full name.
java.lang.String	getDefName() Retrieve the application module definition name.
protected RowSet[]	getDetailRowSets(int rsiId)
java.lang.Object	getDomainValue(java.lang.String className, java.lang.String[] argTypes, java.lang.Object[] argValues)
java.lang.String[]	getEntityAssociationDefNames(java.lang.String packName) Gets the names of the entity association definitions defined in a package.
java.lang.String[]	getEntityDefNames(java.lang.String packName) Return the names of the EntityObject available in the root package.
java.util.Hashtable	getEnvironment() Returns the BC4J context for the session.
long	getEstimatedRowCount(int rsId)
JboExceptionHandler	getExceptionHandler()
int	getFetchedRowCount(int rsiId)
java.lang.String	getFullName() Retrieves the fully-qualified name of this component.
int	getIterMode(int rsiId)
java.util.Locale	getLocale() Get the current Locale
LocaleContext	getLocaleContext() retrieves the locale context for the session
int	getLockingMode() Returns the preferred locking mode for this Transaction.
java.lang.String	getMarshalledTypeName(java.lang.Object obj)
int	getMaxFetchSize(int voId)
int	getMostRecentStackId() Internal: Applications should not use this method.
java.lang.String	getName() Retrieve the name of the particular instance of an object (instance name)
ObjectMarshaller	getObjectMarshaller()
java.lang.String[]	getPackageNames() Gets names of the packages that make up this middle tier application.
java.lang.Object	getParent()
protected byte[]	getPiggyback()
java.util.Hashtable	getProperties() Override PropertyHelper.getProperties
java.lang.String	getQueryOptimizerHint(int voId)
int	getReleaseLevel() Returns the release level that should be employed by clients of this ApplicationModule.
AbstractAppModuleRequestHandler	getRemoteAppModuleRequestHandler()
int	getRemoteId()
int	getRemoteObjectId(java.lang.Object obj)
java.lang.String	getResponseName()
ApplicationModuleImpl	getRootAM()
byte	getROTEntryType()
int	getRowCount(int rsId)
protected RowSetIterator[]	getRowSetIterators(int rsId)
protected RowSet[]	getRowSets(int voId)
protected ServiceMessage	getServiceMessage()
Session	getSession() Gets the Application Module's session.
ClientDocument	getStyles(java.lang.String name) Gets the Style Definitions from the Middle Tier
java.lang.Object	getSyncLock() Gets the locking object for this Application Module.
int	getSyncMode() Returns the sync mode for this Application Module.
Transaction	getTransaction() Gets this Application Module's database transaction.
java.util.Hashtable	getUserData() Returns application context for the session.
java.lang.String[]	getUserRoles() Returns the Roles/Groups for current user principal.
java.lang.String	getVersion() Get the version
java.lang.String[]	getViewDefNames(java.lang.String packName) Return the names of the ViewObject available in the root package.
java.lang.String[]	getViewLinkDefNames(java.lang.String packName) Gets the names of the View Link definitions defined in a package.
java.lang.String[]	getViewLinkNames() Returns an array of the names of the View Links that are currently loaded within this Application Module.
java.lang.String[]	getViewLinkNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes) Returns an array of names of the View Links in this Application Module.
protected int	getViewObjectId(ViewObject vo)
java.lang.String[]	getViewObjectNames() Return the names of the ViewUsages (static and dynamic) defined in this applicationModule.
java.lang.String[]	getViewObjectNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes) Returns an array of names of the View Objects in this Application Module.
void	handleException(java.lang.Exception ex, boolean lastEntryInPiggyback) Catches an exception thrown by the middle tier.
void	handleWarning(JboWarning warn) Catches a warning thrown by the middle tier.
boolean	hasPendingDataPosts()
protected void	init()
protected void	init(java.util.Hashtable env)
java.lang.Object	invokeDomainMethod(Row row, java.lang.String attrId, boolean bringBackDomain, java.lang.String methodName, java.lang.String[] clzNames, java.lang.Object[] args)
java.lang.Object	invokeMethod(java.lang.Object target, java.lang.String methodName, java.lang.String[] argTypeNames, java.lang.Object[] args)
boolean	isBoundToWorkingSet()
boolean	isBundledExceptionMode()
boolean	isClearCacheOnCommit() Returns the flag indicating whether all Entity Object caches will be cleared after the transaction is committed.
boolean	isClearCacheOnRollback() Returns the flag indicating whether all Entity Object caches will be cleared after the transaction is rolled back.
boolean	isClient() Returns whether this session is running as a client in 3 tier or not.
boolean	isConnected() Checks if the transaction is connected to the database.
boolean	isCustomMarshalled(java.lang.Object obj)
boolean	isDetached()
boolean	isDirty() Checks if any data within this Application Module has been modified but not yet committed.
protected static boolean	isEmpty(java.lang.String s)
static boolean	isIgnoreCustomProxies()
boolean	isInWorkingSet()
boolean	isLocal()
boolean	isMarshalledLocally()
boolean	isRemoved()
boolean	isRoot() Returns true if this Application Module is a root Application Module.
boolean	isRowValidation(int rsiId)
boolean	isUserInRole(java.lang.String role)
boolean	isValidIdForUndo(java.lang.String id) Determines if an id created using passivateStateForUndo(String, byte[], int) is still valid.
void	loadPackage(java.lang.String packageName) Loads a package that may be browsed for defined objects.
java.lang.Object	marshal(java.lang.Object obj)
java.lang.Object	marshalForActivate(java.lang.Object obj)
int	passivateState(byte[] clientData)
int	passivateState(byte[] clientData, int flags) Internal: Applications should not use this method.
int	passivateState(int id, byte[] clientData) Internal: Applications should not user this method.
int	passivateState(int id, byte[] clientData, int flags) Internal: Applications should not use this method.
java.lang.String	passivateStateForUndo(java.lang.String id, byte[] clientData, int flags) Create an ApplicationModule undo record.
void	postChanges() Synchronizes the changes in the middle-tier transaction-cache with the database.
void	prepareSession(SessionData info) Internal: Applications should not use this method.
void	processJboException(JboException ex)
protected void	processPiggyback(byte[] pb)
protected com.sun.java.util.collections.ArrayList	processServiceMessage(ServiceMessage svcMsg)
java.lang.Object	readBlobStream(int rsId, int rowId, java.lang.String attrId, int offset, int length)
java.lang.Object	readLob(int rsId, int rowId, java.lang.String attrId, int offset, int length)
java.lang.Object	readLobInternal(int rsId, int rowId, java.lang.String attrId, int offset, int length, boolean isCharStream)
protected java.lang.Object	readMethodResponse(java.lang.String methodName, ServiceMessage sm)
void	readRowSetXML(int rsId, Element elem, int depthCount)
void	readRowXML(int rsiId, RowImpl row, Element elem, int depthCount)
void	reconnect() Re-establish the transaction JDBC connection using previously supplied database credentials.
void	reconnect(boolean force) Reconnect the application module to the database, if necessary, using previously supplied database credentials.
java.lang.Object	refreshProperty(java.lang.String hintName) Retrieves the specified property, if it exists.
java.lang.Object	refreshVOProperty(int voId, java.lang.String hintName)
void	remove() Deletes this component.
void	removeChangeSet(int id) Removes the change set that defines the changes to EntityImpls within a transaction.
void	removeClientPostListener(ClientPostListener l)
void	removeState(int id) Internal: Applications should not use this method.
void	removeTransactionStateListener(TransactionStateListener target) Remove this transaction listener (if it exists) from this transaction.
void	removeViewClearCacheListener(ViewClearCacheListener target)
int	reservePassivationId() Internal: Applications should not user this method.
int	reserveSnapshotId(int flags) Internal: Applications should not use this method.
void	resetMarshaller()
void	resetState(boolean reload)
void	resetState(int flags) Internal: Applications should not use this method.
ResponseValues	riGetApplicationModuleInfo()
java.lang.Object	riInvokeExportedMethod(java.lang.Object target, java.lang.String methodName, java.lang.String[] argTypes, java.lang.Object[] args)
void	riRemove()
void	rollback() Discards all modifications made in this transaction.
ServiceMessage	sendServiceMessage(ServiceMessage svcMsgIn)
ServiceMessage	sendWorkingSetRequests(java.lang.String reqName, WSApplicationModuleImpl wsAM, ServiceMessage msg)
void	setBoundToWorkingSet(boolean b)
void	setBundledExceptionMode(boolean flag) Set this transaction into bundled exception mode.
void	setClearCacheOnCommit(boolean val) Sets the value of the flag indicating whether all Entity Object caches will be cleared after the transaction is committed.
void	setClearCacheOnRollback(boolean val) Sets the value of the flag indicating whether all Entity Object caches will be cleared after the transaction is rolled back.
void	setDataModelRefresh(boolean b)
void	setExceptionHandler(JboExceptionHandler hndlr) Sets the exception handler for this Application Module.
static void	setIgnoreCustomProxies(boolean ignore)
void	setIterMode(int rsiId, int mode)
void	setLocale(java.util.Locale locale) Set a new Locale
void	setLockingMode(int mode) Sets the preferred locking mode for this Transaction.
void	setMaxFetchSize(int voId, int max)
void	setProperty(java.lang.String hintName, java.lang.Object hintValue)
void	setQueryOptimizerHint(int voId, java.lang.String hint)
void	setReleaseLevel(int releaseLevel)
void	setRemoteAppModuleRequestHandler(AbstractAppModuleRequestHandler reqHandler)
void	setRowValidation(int rsiId, boolean flag)
void	setStoreForPassiveState(byte storageType) Internal: Applications should not use this method.
void	setStyles(java.lang.String name, ClientDocument clientDocument) Saves the Style Definitions to the Middle Tier
void	setSyncMode(int mode) Sets the data synchronization mode between the client and the middle tier.
void	setVOProperty(int voId, java.lang.String hintName, java.lang.Object hintValue)
void	sync() Synchronise all the ResultSets defined in this ApplicationModule with the server.
void	syncMarshaller(ServiceMessage svcMsg)
void	syncWorkingSet(WSApplicationModuleImpl wsAM)
protected java.lang.String	toEmpty(java.lang.String s)
java.lang.Object[]	transformExceptionParams(ViewObject[] vos, java.lang.String entityDefName, java.lang.String className, java.lang.Object[] params) Internal: Applications should not use this method. This method uses findViewObjectUsingEntity() to get the first ViewObject that this entity is used in and then transforms the parameters from a given JboException from their Entity layer equivalents to the ViewObject equivalents.
void	transPostPushback(int hdl) Internal: Applications should not use this method.
void	transPostRefresh(int refreshMode, int hdl)
void	transPostRemove(int hdl) Internal: Applications should not use this method.
void	transPostRevert(int hdl) Internal: Applications should not use this method.
java.lang.Object	unMarshal(java.lang.Object obj)
void	validate() Starts the validation cycle and validates all subscribers in the ValidationListener list.
void	writeClob(int rsId, int rowId, java.lang.String attrId, char[] data)
void	writeLob(int rsId, int rowId, java.lang.String attrId, byte[] data)
Node	writeRowSetXML(int rsId, int depthCount, long options)
Node	writeRowSetXMLWithMap(int rsId, long options, com.sun.java.util.collections.HashMap map)
Node	writeRowXML(int rsiId, RowImpl row, int depthCount, long options)
Node	writeRowXMLWithMap(int rsiId, RowImpl row, long options, com.sun.java.util.collections.HashMap map)

Methods inherited from class oracle.jbo.common.PropertiesHelper

getProperty

Methods inherited from class java.lang.Object

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

Methods inherited from interface oracle.jbo.Properties

getProperty

Field Detail

mRemoved

protected boolean mRemoved

Constructor Detail

ApplicationModuleImpl

public ApplicationModuleImpl()

Method Detail

setRemoteAppModuleRequestHandler

public void setRemoteAppModuleRequestHandler(AbstractAppModuleRequestHandler reqHandler)

getRemoteAppModuleRequestHandler

public AbstractAppModuleRequestHandler getRemoteAppModuleRequestHandler()

init

protected void init()

init

protected void init(java.util.Hashtable env)

isRemoved

public boolean isRemoved()

isLocal

public boolean isLocal()

Specified by:

isLocal in interface AppModuleRequestHandler

getSyncLock

public final java.lang.Object getSyncLock()

Description copied from interface: ApplicationModule

Gets the locking object for this Application Module. Note that if this method is invoked on a nested Application Module, the root Application Module's locking object is returned. This is because the locking object is shared by all Application Modules contained by the root Application Module.

This locking object should be used to synchronize multiple calls into BC4J. The client application code rarely needs to worry about synchronization. It is the middle tier (the server) code that needs to synchronize calls into the middle tier to serialize updates to shared middle tier objects.

Here is an example of how to synchronize access using this method:

    synchronized(am.getSyncLock())
    {
       // Code that needs to execute serially.
    }
 

Specified by:

getSyncLock in interface ApplicationModule

Returns:

the locking object.

getRootAM

public ApplicationModuleImpl getRootAM()

getParent

public java.lang.Object getParent()

Specified by:

getParent in interface ClientComponentObject

getPackageNames

public java.lang.String[] getPackageNames()

Description copied from interface: Session

Gets names of the packages that make up this middle tier application.

Specified by:

getPackageNames in interface Session

Returns:

The package names.

createApplicationModule

public ApplicationModule createApplicationModule(java.lang.String amName,
                                                 java.lang.String defName)

Create a ApplicationModule using its class name and specify its name

Specified by:

createApplicationModule in interface ApplicationModule

Parameters:

amName - The name to assign to the ApplicationModule

defName - the name of the Application Module definition from which the new nested Application Module is to be created. It must be a fully qualified definition name (including the package name). If ApplicationModule.DEFAULT_DEF_FULL_NAME or null is passed, a generic Application Module (one without custom code or static Component Objects) is created.

Returns:

an ApplicationModule

isEmpty

protected static boolean isEmpty(java.lang.String s)

findApplicationModule

public ApplicationModule findApplicationModule(java.lang.String amName)

Get an ApplicationModule using its name.

Specified by:

findApplicationModule in interface ApplicationModule

Parameters:

amName - The name of the ApplicationModule

Returns:

an ApplicationModule

getApplicationModuleDefNames

public java.lang.String[] getApplicationModuleDefNames(java.lang.String packName)

Return the names of the ApplicationModule class.

Specified by:

getApplicationModuleDefNames in interface Session

Parameters:

packName - the name of the package.

Returns:

Array of class names

getAllApplicationModuleDefNames

public java.lang.String[] getAllApplicationModuleDefNames()

Return the name of the ApplicationModule class and all the nested ApplicationModule

Specified by:

getAllApplicationModuleDefNames in interface Session

Returns:

Array of class names

getApplicationModuleNames

public java.lang.String[] getApplicationModuleNames()

Return the names of the ApplicationModules.

Specified by:

getApplicationModuleNames in interface ApplicationModule

Returns:

Array of names

See Also:

ApplicationModule.findApplicationModule(String)

getApplicationModuleNames

public java.lang.String[] getApplicationModuleNames(boolean inclLoadedOnes,
                                                    boolean inclNotLoadedOnes)

Description copied from interface: ApplicationModule

Returns an array of names of the nested Application Modules in this Application Module.

This method allows the user to control whether the returning names are those of loaded (instantiated) nested Application Modules, or those of not yet loaded (uninstantiated) nested ApplicationModules, or both. Not yet loaded Application Modules would appear only if lazy loading is turned on.

Note that ApplicationModule.getApplicationModuleNames() is equivalent to getApplicationModuleNames(true, false).

If this method is called with loadedOnes = true and fromDef = true, both loaded and not-yet-loaded Application Module names are returned. No duplicate name is returned. Note that loaded Application Modules include dynamically created ones.

Specified by:

getApplicationModuleNames in interface ApplicationModule

Parameters:

inclNotLoadedOnes - if true, names of the child Application Modules from the Application Module definition are returned. Some of these child AMs could have already been loaded and some may have not yet been loaded.

Returns:

an array of nested Application Module names. If this Application Module contains no nested Application Module, it returns an empty array, i.e., new String[0].

connect

public void connect(java.lang.String url)

Make a physical connection to a database server.

Specified by:

connect in interface Transaction

Parameters:

url - a database url of the form jdbc:subprotocol:subname.

connect

public void connect(java.lang.String url,
                    java.util.Properties info)

Make a physical connection to a database server.

Specified by:

connect in interface Transaction

Parameters:

url - a database url of the form jdbc:subprotocol:subname.

info - a list of arbitrary string tag/value pairs to be used as connection arguments. Normally, at least "user" and "password" properties should be included.

connect

public void connect(java.lang.String url,
                    java.lang.String user,
                    java.lang.String password)

Make a physical connection to a database server.

Specified by:

connect in interface Transaction

Parameters:

url - a database url of the form jdbc:subprotocol:subname.

user - the database user on whose behalf the connection is being made.

password - the user's password.

connectToDataSource

public void connectToDataSource(java.lang.String nsUrl,
                                java.lang.String nsUser,
                                java.lang.String nsPasswd,
                                java.lang.String dataSourceName)

Description copied from interface: Transaction

Looks up a datasource from Oracle 8i namespace using the jdbc_access protocol and acquires the default jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection() method.

Specified by:

connectToDataSource in interface Transaction

Parameters:

nsUrl - Url to the jndi namespace where the datasource is bound

nsUser - User name that is used to access the namespace.

nsPasswd - nsUsers' passwd

connectToDataSource

public void connectToDataSource(java.lang.String nsUrl,
                                java.lang.String nsUser,
                                java.lang.String nsPasswd,
                                java.lang.String dataSourceName,
                                java.lang.String user,
                                java.lang.String password)

Description copied from interface: Transaction

Looks up a datasource from Oracle 8i namespace using the jdbc_access protocol and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String password) method.

Specified by:

connectToDataSource in interface Transaction

Parameters:

nsUrl - Url to the jndi namespace where the datasource is bound

nsUser - User name that is used to access the namespace.

nsPasswd - nsUsers' passwd

user - Username for which the connection is acquired from the datasource

password - User's password.

connectToDataSource

public void connectToDataSource(java.util.Hashtable initialContextEnv,
                                java.lang.String dataSourceName,
                                java.lang.String user,
                                java.lang.String passwd,
                                boolean isXABased)

Description copied from interface: Transaction

Looks up a datasource from a jndi tree and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String passwd) method.

Specified by:

connectToDataSource in interface Transaction

Parameters:

initialContextEnv - Envirionment used the create initial context. May be null.

user - Username for which the connection is acquired from the datasource

passwd - User's password.

isXABased - True if datasource is XADataSource implementation. If true, the tranasction is assumed to be controlled by an external transaction manager.

connectToDataSource

public void connectToDataSource(java.util.Hashtable initialContextEnv,
                                java.lang.String dataSourceName,
                                boolean isXABased)

Description copied from interface: Transaction

Looks up a datasource from a jndi tree and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String passwd) method.

Specified by:

connectToDataSource in interface Transaction

Parameters:

initialContextEnv - Envirionment used the create initial context. May be null.

isXABased - True if datasource is XADataSource implementation. If true, the tranasction is assumed to be controlled by an external transaction manager.

getConnectionMetadata

public ConnectionMetadata getConnectionMetadata()

Description copied from interface: Transaction

Returns a metdata structure that describes the transaction's JDBC connection.

Specified by:

getConnectionMetadata in interface Transaction

isConnected

public boolean isConnected()

Description copied from interface: Transaction

Checks if the transaction is connected to the database. In a three-tier scenario, clients can call this method to check if the middle tier is connected to the database.

Specified by:

isConnected in interface Transaction

Returns:

true if connected; false if disconnected.

reconnect

public void reconnect(boolean force)

Description copied from interface: Transaction

Reconnect the application module to the database, if necessary, using previously supplied database credentials. If the parameter is true, then a database disconnect and reconnect is performed, whatever the current connection state. If false, the connect is only performed if the connection has disappeared.

Specified by:

reconnect in interface Transaction

Parameters:

force - force a reconnect, should usually be false.

reconnect

public void reconnect()

Description copied from interface: Transaction

Re-establish the transaction JDBC connection using previously supplied database credentials.

If the application module was previously disconnected using disconnect(true) (retain application module state) then this method should only re-establish the transaction JDBC connection.

If the application module was previously disconnected using disconnect(false) (do not retain application module state) then this method should re-establish the transaction JDBC connection and reset the application module non-transactional state which may include child view usage and application module usage instances.

Specified by:

reconnect in interface Transaction

disconnect

public void disconnect()

Performe clean-up when client is disconnecting by dereferencing the remote instances.

Specified by:

disconnect in interface Transaction

disconnect

public void disconnect(boolean retainState)

Description copied from interface: Transaction

Closes the JDBC connection object. If disconnect is invoked with retainState equal to false then the JDBC connection will be closed and this transaction will be removed from the root application module.

If disconnect is invoked with retainState equal to true then this transaction's JDBC connection will be closed but, the root application module will continue to reference this transaction and its state. The transaction state may include unposted database changes and cached result sets. In the middle tier, reconnect on the DBTransaction interface may be invoked to re-establish a JDBC connection for this transaction. If connection pooling is enabled for this middle tier instance this connection may represent a recycled connection.

The developer should take measures to ensure that the following requirements are met before attempting to disconnect a JDBC connection and retain application module state. All of these validations are not currently performed by the disconnection implementation because of performance considerations:

All non-forward only view objects should have fetched in all data

If pessimistic locking is enabled, all pending changes should be commited/rolled back.

All changes that have been posted to the database should be commited/rolled back.

Specified by:

disconnect in interface Transaction

validate

public void validate()

Description copied from interface: Transaction

Starts the validation cycle and validates all subscribers in the ValidationListener list. Typically all top-level entities which were invalidated through the framework will be in this list. Listeners are removed as they are validated.

The advantage of calling validate() is that the data stays in the middle tier. Data is not posted to the database, thus avoiding the possible firing of database triggers or constraints.

Specified by:

validate in interface Transaction

addClientPostListener

public void addClientPostListener(ClientPostListener l)

removeClientPostListener

public void removeClientPostListener(ClientPostListener l)

postChanges

public void postChanges()

Description copied from interface: Transaction

Synchronizes the changes in the middle-tier transaction-cache with the database.

This method bypasses the validation cycle and can allow invalid data to be posted to the database. As a side effect of this method, database triggers or other constraints might be fired as a result of posting data. However, invalid changes cannot be committed, as the commit() method validates all changes before committing them.

Typically, applications should call this method if they must execute SQL operations or queries with the current cached-state of data, before validating the changes.

Specified by:

postChanges in interface Transaction

See Also:

Transaction.commit()

doPostChanges

public void doPostChanges()

transPostPushback

public void transPostPushback(int hdl)

Description copied from interface: TransPostControl

Internal: Applications should not use this method.

Specified by:

transPostPushback in interface TransPostControl

transPostRemove

public void transPostRemove(int hdl)

Description copied from interface: TransPostControl

Internal: Applications should not use this method.

Specified by:

transPostRemove in interface TransPostControl

transPostRevert

public void transPostRevert(int hdl)

Description copied from interface: TransPostControl

Internal: Applications should not use this method.

Specified by:

transPostRevert in interface TransPostControl

transPostRefresh

public void transPostRefresh(int refreshMode,
                             int hdl)

Specified by:

transPostRefresh in interface TransPostControl

isDirty

public boolean isDirty()

Description copied from interface: Transaction

Checks if any data within this Application Module has been modified but not yet committed. This method is typically called before an attempt is made to post the data.

For example, this method can be called when the user at the client attempts to close an application. If there is unsaved data, this method can return true. In response, the client can prompt the user to save before closing the application.

Specified by:

isDirty in interface Transaction

Returns:

true if the local data and the database differ.

commit

public void commit()

Execute a commit of the server to the database.

Specified by:

commit in interface Transaction

See Also:

TransactionListener.beforeCommit(TransactionEvent), TransactionListener.afterCommit(TransactionEvent), DBTransaction, Transaction.postChanges()

commitAndSaveChangeSet

public int commitAndSaveChangeSet()

Description copied from interface: Transaction

Commits the transaction and writes updated EntityImpls to the persistent store.

This method (along with applyChangeSet and removeChangeSet is used to synchronize the cache between root Application Module instances in an Application Module pool.

commitAndSaveChangeSet commits the transaction, but during the commit process, writes out "changed" EntityImpls to the persistent store. These changes are stored as a "change set". The change set can then be applied to other transactions (that is, to the Entity caches of other root Application Modules).

The integer value returned by this method identifies the change set that is stored in persistent store.

To apply the changes to another transaction (or Application Module cache), call Transaction.applyChangeSet(int) where int is the integer value returned by commitAndSaveChangeSet that represents the change set.

For example, assume you have two root Application Modules, named am1 and am2, in an Application Module pool.

  // The line below commits the transaction in am1 and writes the change
  // set to persistent store (database table).  The returning snapId
  // identifies the (persistent) change set.

  int snapId = am1.getTransaction().commitAndSaveChangeSet();

  // Use that change set and apply the changes to the other Application
  // Module, am2.  That is, apply changes from am1 to am2.

  am2.getTransaction().applyChangeSet(snapId);

  // When you are done with the change set, remove (free) it.

  am1.getTransaction().removeChangeSet(snapId);
 

Specified by:

commitAndSaveChangeSet in interface Transaction

Returns:

an integer representing an EntityImpl change set in persistent store.

See Also:

Transaction.applyChangeSet(int), Transaction.removeChangeSet(int)

rollback

public void rollback()

Description copied from interface: Transaction

Discards all modifications made in this transaction. This method is called on the Application Module's transaction. For example:

     appMod.getTransaction().rollback();
 

When this method is invoked, beforeRollback events are posted to the listeners, the changes are discarded, afterRollback events are posted, and transient listeners are deleted from the transaction. For both events, non-transient listeners preceed transient listeners.

In the following example, a method named updateAttr has been implemented to update a row of a View Object vo with the value newAttrVal. If updateAttr succeeds (returns true), the code commits the transaction; otherwise, it rolls the transaction back:

 // Assume that appMod has been declared and initialized elsewhere.
   try {  if (updateAttr(vo, newAttrVal)) {
       // Commit changes to the database, making
       // updated data available to other Application Modules.
       appMod.getTransaction().commit();
       System.out.println("\n Transaction committed. \n");
     }
   else {
       appMod.getTransaction().rollback();
       System.out.println("\n Transaction rolled back. \n");
    }
 } catch (Exception e) {
       e.printStackTrace();
 }
 

Note, if your Application Module is an EJB session bean, a new transaction is started for you automatically after calling rollback. You do not have to explicitly start a new transaction.

Specified by:

rollback in interface Transaction

See Also:

DBTransaction, TransactionListener.afterRollback(TransactionEvent), TransactionListener.beforeRollback(TransactionEvent)

sendServiceMessage

public ServiceMessage sendServiceMessage(ServiceMessage svcMsgIn)

Specified by:

sendServiceMessage in interface SvcMsgSender

sync

public void sync()

Synchronise all the ResultSets defined in this ApplicationModule with the server. Any changes in the ResultSets are flushed to the server and the server updates are piggybacked to the client.

Specified by:

sync in interface ApplicationModule

isBoundToWorkingSet

public boolean isBoundToWorkingSet()

setBoundToWorkingSet

public void setBoundToWorkingSet(boolean b)

Specified by:

setBoundToWorkingSet in interface WSApplicationModuleMarshaller

setSyncMode

public void setSyncMode(int mode)

Description copied from interface: ApplicationModule

Sets the data synchronization mode between the client and the middle tier. There are two sync modes: ApplicationModule.SYNC_LAZY and ApplicationModule.SYNC_IMMEDIATE.

SYNC_LAZY is typically more efficient in that it causes fewer round trips to the middle tier.

Note that the sync mode is an attribute of the root Application Module. If one calls getSyncMode or setSyncMode on a nested Application Module, it is routed to the root Application Module. Also, note that pending changes are managed at the root Application Module. When the changes are flushed from the client to the middle tier, all changes pending under the root Application Module are flushed.

Specified by:

setSyncMode in interface ApplicationModule

Parameters:

mode - the new synchronization mode: SYNC_LAZY or SYNC_IMMEDIATE.

See Also:

ApplicationModule.getSyncMode(), ApplicationModule.SYNC_LAZY, ApplicationModule.SYNC_IMMEDIATE

getSyncMode

public int getSyncMode()

Description copied from interface: ApplicationModule

Returns the sync mode for this Application Module.

Note that the sync mode is an attribute of the root Application Module. If one calls getSyncMode or setSyncMode on a nested Application Module, it is routed to the root Application Module. Also, note that pending changes are managed at the root Application Module. When the changes are flushed from the client to the middle tier, all changes pending under the root Application Module are flushed.

Specified by:

getSyncMode in interface ApplicationModule

Returns:

the sync mode: SYNC_LAZY or SYNC_IMMEDIATE.

See Also:

ApplicationModule.setSyncMode(int mode), ApplicationModule.SYNC_LAZY, ApplicationModule.SYNC_IMMEDIATE

isInWorkingSet

public boolean isInWorkingSet()

Specified by:

isInWorkingSet in interface ObjectMarshaller

getVersion

public java.lang.String getVersion()

Get the version

Specified by:

getVersion in interface Session

Returns:

the version

getLocale

public java.util.Locale getLocale()

Get the current Locale

Specified by:

getLocale in interface Session

Returns:

the current Locale

setLocale

public void setLocale(java.util.Locale locale)

Set a new Locale

Specified by:

setLocale in interface Session

Parameters:

locale -

setStoreForPassiveState

public void setStoreForPassiveState(byte storageType)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Determines where the Application Module will store serialized versions of its session-state, plus any cached changes. This information can be stored to the database, to a file, or to memory, based on the value of the storageType parameter. The storageType can be set to:

• ApplicationModule.PASSIVATE_TO_DATABASE (default target)
• ApplicationModule.PASSIVATE_TO_FILE
• ApplicationModule.PASSIVATE_TO_MEMORY

This method should be called before calling ApplicationModule.passivateState(byte[]). Note that once an Application Module has serialized its state, it cannot be asked to change its store. This method will throw an JboException if this Application Module has already stored its state earlier.

For example, the following code will set the storage to database, file, or memory, based on the value of the str parameter. Database is the default target:

 String str =
    oracle.jbo.common.JboEnvUtil.getProperty("jbo.test.passivateStateTo");
 if (str != null)
 {
    if (str.equals("file"))
    {
      appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_FILE);
    }
    else
    if (str.equals("memory"))
    {
      appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_MEMORY);
    }
 

Specified by:

setStoreForPassiveState in interface ApplicationModule

Parameters:

storageType - where the Application Module state is stored. Can be one of ApplicationModule.PASSIVATE_TO_DATABASE (default target), ApplicationModule.PASSIVATE_TO_FILE, or ApplicationModule.PASSIVATE_TO_MEMORY.

See Also:

ApplicationModule.passivateState(byte[])

findViewObjectUsingEntity

public ViewObject findViewObjectUsingEntity(ViewObject[] vos,
                                            java.lang.String entityDefName,
                                            java.lang.String[] attrNames)

Description copied from interface: ApplicationModule

Given an array of View Objects (the vos parameter), finds the first matching View Object. It uses the following rules to determine if the View Object matches the description.

• Does the View Object use the specified Entity (entityName) as one of its Entity bases?
• If attrName is not empty, is one of the View Object's attributes mapped to the Entity's attribute whose name is attrName[0]? If attrName is empty, i.e., it is either null or has no element, then this rule is skipped.
• If the View Object passes the above two rules, then a check is made to see if the Entity base in this View Object is updateable or not. If it is, this View Object is returned. If it is not, we continue until we find one that with an updateable Entity base or until we exhaust the vos array. If none of the View Objects that pass the first two rules has an updateable Entity base, the first View Object that passed the first two rules is returned.

The method is used to find a View Object that can be used to edit an Entity Object's attribute. If a matching View Object is identified, and if attrName coming in was not empty, the View Object's attribute name is copied into the attrName.

Specified by:

findViewObjectUsingEntity in interface ApplicationModule

Parameters:

vos - an array of possible View Objects.

entityDefName - fully qualified name of the Entity object. Should not be null.

attrNames - if empty, i.e., null or an array of length 0, then the attribute matching rule will be skipped (see the above discussion). If not empty, it should have only one element and that element should be the name of an attribute of the Entity. The attribute matching rule will apply. If a matching View Object is found, attrName[0] upon return should have the name of a View Object mapped to the Entity attribute.

transformExceptionParams

public java.lang.Object[] transformExceptionParams(ViewObject[] vos,
                                                   java.lang.String entityDefName,
                                                   java.lang.String className,
                                                   java.lang.Object[] params)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method. This method uses findViewObjectUsingEntity() to get the first ViewObject that this entity is used in and then transforms the parameters from a given JboException from their Entity layer equivalents to the ViewObject equivalents. This method is primarily used by JboException subclasses to map their parameters when doEntityToVOMapping() is called on those Exceptions.

Specified by:

transformExceptionParams in interface ApplicationModule

Parameters:

vos - an array of possible View Objects.

entityDefName - fully qualified name of the Entity object. Should not be null.

className - Qualified classname for the Exception which is being mapped

params - Parameters from the Exception that is to be transformed into ViewObject equivalents.

reservePassivationId

public int reservePassivationId()

Description copied from interface: ApplicationModule

Internal: Applications should not user this method.

Specified by:

reservePassivationId in interface ApplicationModule

reserveSnapshotId

public int reserveSnapshotId(int flags)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Reserves a unique indentifier which may later be specified when passivating AM state as the identifier to be used for re-establishing AM state.

If the PASSIVATE_TRANSIENT_FLAG has not been set then this method will return a passivation id from one of the persistent Serializers (File and Database). This method will then reserve a stack snapshot id for that persistent snapshot. The reserved stack id may be acquired by invoking ApplicationModule.getMostRecentStackId().

If the PASSIVATE_TRANSIENT_FLAG has been set then this method will return a stack id. The stack id is unique for a session transaction only. This may need to be extended to provide a UUID so that applications do not inadvertantly try to undo state across transaction boundaries.

This method may be invoked to obtain a unique snapshot identifier before a snapshot is actually acquired. An example use case is an HTTP servlet that must encode all URLs with the snapshot id before the snapshot is acquired.

Specified by:

reserveSnapshotId in interface ApplicationModule

Parameters:

flags - a bit map defining passivation flags.

Returns:

a unique integer identifier that may later be used to passivate and activate Application Module state

See Also:

#passivateState(int, byte[], flags).

getMostRecentStackId

public int getMostRecentStackId()

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Acquire the snapshot id of the most recent stack snapshot. This method may be used by clients to acquire the stack snapshot id of a persistent snapshot.

Please see #passivateToStack(byte[]) for more information regarding stack passivation.

Specified by:

getMostRecentStackId in interface ApplicationModule

beforePassivateState

public void beforePassivateState()

passivateState

public int passivateState(int id,
                          byte[] clientData)

Description copied from interface: ApplicationModule

Internal: Applications should not user this method.

Specified by:

passivateState in interface ApplicationModule

passivateState

public int passivateState(byte[] clientData)

Specified by:

passivateState in interface ApplicationModule

passivateState

public int passivateState(int id,
                          byte[] clientData,
                          int flags)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Serializes the current state of this Application Module's session, along with all changes cached, to a byte array and returns a unique identifier with which to re-establish the state.

This method accepts an id which represents the unique identifier that should be used to re-establish the application module state. The id must have been generated by invoking ApplicationModule.reserveSnapshotId(int).

The same snapshot type bit which was specified when the snapshot id was reserved should be specified when this method is invoked. For example, if reserveSnapshotId was invoked with the PASSIVATE_TRANSIENT_FLAG set then this method should be invoked with the PASSIVATE_TRANSIENT_FLAG set. Failing to do so may result in invalid snapshot id exceptions.

For more information regarding passivation please see ApplicationModule.passivateState(byte[], int).

Specified by:

passivateState in interface ApplicationModule

Parameters:

id - a reserved passivation id

clientData - cached changes, or any information that a client might want to store.

flags - a bit map defining passivation flags.

Returns:

a unique integer identifier associated with an instance of the Application Module.

See Also:

oracle.jbo.server.ApplicationModule#reservePassivationId()

passivateState

public int passivateState(byte[] clientData,
                          int flags)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Creates a snapshot of the current state of thie ApplicationModule's session. If the PASSIVATE_TRANSIENT_FLAG is not set then the snapshot bytes will be serialized to a persistent store (database or file). If the PASSIVATE_TRANSIENT_FLAG bit is set then the snapshot bytes will be pushed to the ApplicationModule snapshot stack. The method will then return a unique identifier which may be used to activate the state. Please note that the same snapshot type bit should be used to activate the state as was used to passivate the state. Failing to do so could result in the snapshot record not being located.

This method always works from the top-level Application Module. If you have nested Application Modules and you call this method on a inner Application Module, it will still work from the top-level module.

In contrast to ApplicationModule.activateState(int, SessionData, int), which deserializes a session-state from the persistent store, calling passivateState, does not affect the transaction state.

The cached changes, or clientData, can be any information that a client might want to store. For example, a JSP client could store the additional client-state information in this byte array so that when the JSP client becomes active and connects to an Application Module later, it could get its passivated state from the Application Module. This would reduce the amount of state information stored at the client side to a bare minimum (typically just an Application Module persistence ID).

A value of null for clientData indicates that the state will be stored, but there is no client data to be preserved.

This method preserves currency. When ApplicationModule.activateState(int, SessionData, int) is called, the active row is returned.

For example, the following code snippet inserts a new row in a View Object, then calls passivateState to save the Application Module state. The transaction is rolled back and activateState is called. The value of getCurrentRow called before the passivateState should match the the value of getCurrentRow called after activateState.

 // create a View Object "depts"
 ViewObject depts = appModule.createViewObject("myDeptView", "myDeptViewDef");

 // insert a new row into depts
 Row r = depts.createRow();
 r.setAttribute("DeptNum","56");
 depts.insertRow(r);

 Row afterInsert = depts.getCurrentRow();

 // Passivate the Application Module state
 int id = appModule.passivateState(null);

 // rollback the transaction
 appModule.getTransaction.rollback();

 // move the cursor to the last row -- just to make it interesting
 depts.last();

 // now activate the Application Module state
 // currency should be on the new row inserted.
 appModule.activateState(id, SessionData, int);

 Row afterActivate = depts.getCurrentRow();
 

The values afterInsert and afterActivate should be the same.

Specified by:

passivateState in interface ApplicationModule

Parameters:

clientData - cached changes, or any information that a client might want to store.

flags - a bit map defining passivation flags.

Returns:

a unique integer identifier associated with an instance of the Application Module.

passivateStateForUndo

public java.lang.String passivateStateForUndo(java.lang.String id,
                                              byte[] clientData,
                                              int flags)

Description copied from interface: ApplicationModule

Create an ApplicationModule undo record.

ApplicationModule state that is passivated using this method will have transaction scope only -- the passivated state will be removed when a transaction commit/rollback occurs.

ApplicationModule state snapshots that are created using this method will be pushed to an LIFO stack. This stack is defined as part of the ApplicationModule transaction state and as such will be maintained by ApplicationModule passivation/activation.

The application developer may specify their own snapshot id by passing an id in for the request. If no id has been specified then an id will be generated by the system and returned. If a snapshot already exists for this transaction with the specified id then the old snapshot will be removed from the snapshot stack.

The application developer may control whether a persistent snapshot (on-disk) or a transient snapshot (in-memory) is taken with the BC4J session property, PropertyConstants.ENV_SNAPSHOT_STORE_UNDO.

A value of PropertyConstants.SNAPSHOT_STORE_PERSISTENT (default) directs the algorithm to create a persistent snapshot (on-disk) for this undo request. The location of the persistent snapshot may further be controlled by the BC4J propery PropertyConstants.ENV_PASSIVATION_STORE which accepts values of {file,database}.

A value of PropertyConstants.SNAPSHOT_STORE_TRANSIENT directs the algorithm to create a transient snapshot (in-memory). Transient snapshots are not guaranteed to be maintained in the event of system failure.

Setting the flags parameter value to ApplicationModule.PASSIVATE_DEFER_FLAG allows the snapshot creation to be deferred until the application module is checked in. For typical web-based applications, this means that the snapshot would be created at the end of the request when the application module checkin is invoked.

Most applications using the application module pool are highly encouraged to use this flag value for performance and memory usage optimization. Deferring the snapshot creation allows one snapshot to be used for both transaction undo and failover support.

Deferred passivation should not be requested if it is necessary to capture the ApplicationModule state at the time of the undo request -- a deferred undo request does not guarantee that the passivated state equals the ApplicationModule state at the time of the undo request.

Specified by:

passivateStateForUndo in interface ApplicationModule

Parameters:

id - the id which is to be used to identify this undo record. The id should be unique within a transaction. If an id is not specified then an id will be generated by the system and returned.

clientData - a byte array representing any clientData which the invoker wishes to associate with the undo record.

flags - an int representing passivateStateForUndo flags. Valid flags are:

ApplicationModule.PASSIVATE_DEFER_FLAG see the discussion above for more information regarding the use of this flag.

In order to specify default behaviour the application developer may pass 0 for the flags parameter. Default behaviour is defined as immediate passivation.

activateState

public byte[] activateState(int id,
                            boolean remove)

Specified by:

activateState in interface ApplicationModule

activateState

public byte[] activateState(int id,
                            boolean remove,
                            SessionData info)

Specified by:

activateState in interface ApplicationModule

activateState

public byte[] activateState(int id,
                            SessionData info,
                            int flags)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Deserializes a session-state from the persistent store based on the given id. This method always works from the top-level Application Module. If you have nested Application Modules and you call this method on a inner Application Module, it will still work from the top-level module.

When the PERSISTENT_SNAPSHOT bit is set then this method will attempt to locate the snapshot bytes in a persistent store (database or file). If the PERSISTENT_SNAPSHOT(/tt> bit is not set then this method will locate the snapshot bytes on the stack.

When this method is called, the rows that are updated are locked; new rows are inserted into the transaction cache and posted. This is in contrast to ApplicationModule.passivateState(byte[], int), which does not affect the transaction state.

The activateState method preserves currency. When it is called, it will return the row that was active when ApplicationModule.passivateState(byte[], int) was called. For an example usage of activateState, see ApplicationModule.passivateState(byte[], int).

If the REMOVE_SNAPSHOT bit is set in the flags then the activation framework will remove the snapshot from the persistent store after activation.

It is up to the developer to devise a clean-up strategy for the redundant store.

Specified by:

activateState in interface ApplicationModule

Parameters:

id - a unique integer identifier associated with an instance of the Application Module.

Returns:

a byte array containing any client information that was originally stored with the ApplicationModule.passivateState(byte[], int) method.

activateStateForUndo

public byte[] activateStateForUndo(java.lang.String id,
                                   int flags)

Description copied from interface: ApplicationModule

Restore an ApplicationModule undo record.

Activates an ApplicationModule state which was created using ApplicationModule.passivateStateForUndo(String, byte[], int).

If the id is not on the undo stack then an exception will be thrown indicating that it is an invalid undo id.

Invoking this method will remove all those undo records that are above (more recent) than the specified undo record.

Specified by:

activateStateForUndo in interface ApplicationModule

Parameters:

id - the id of an undo record that was created using ApplicationModule.passivateStateForUndo(String, byte[], int)

isValidIdForUndo

public boolean isValidIdForUndo(java.lang.String id)

Description copied from interface: ApplicationModule

Determines if an id created using ApplicationModule.passivateStateForUndo(String, byte[], int) is still valid.

An id may become invalid if a transaction boundary (commit/rollback) has occured since the id was created.

Specified by:

isValidIdForUndo in interface ApplicationModule

Parameters:

id - the id of an undo record that was created using ApplicationModule.passivateStateForUndo(String id, byte[] clientData, int flags)

prepareSession

public void prepareSession(SessionData info)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Specified by:

prepareSession in interface ApplicationModule

removeState

public void removeState(int id)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Removes the Application Module's session-state, and any cached change information, from the persistent store based on the given id. For example:

 appModule.removeState(id);
 

Specified by:

removeState in interface ApplicationModule

Parameters:

id - an unique integer identifier associated with an instance of the Application Module.

resetState

public void resetState(boolean reload)

Specified by:

resetState in interface ApplicationModule

resetState

public void resetState(int flags)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Applications should override/extend ApplicationModuleImpl.reset() to reset custom ApplicationModule state. reset() is invoked by the internal resetState before resetState begins cleaning up internal ApplicationModuel state.

Flag usage:

RESET_RELOAD_FLAG directs resetState to eagerly reload the ApplicationModule compoonents.

RESET_ROLLBACK_FLAG directs resetState to rollback the ApplicationModule.

RESET_INTERNAL_FLAG directs resetState to perform an internal reset only. The ApplicationPool uses this to reset a managed state ApplicationModule while also managing the previous session's state. For example, when RESET_INTERNAL has been specified the reset will not remove the persistent snapshot records on the snapshot stack.

Resets the non-transaction state of an application module. For example:

 appModule.resetState(false);
 

Specified by:

resetState in interface ApplicationModule

applyChangeSet

public void applyChangeSet(int id)

Description copied from interface: Transaction

Applies the changes committed by another transaction in order to synchronize caches between root Application Module instances.

This method (along with commitAndSaveChangeSet and removeChangeSet is used to synchronize the cache between root Application Module instances in an Application Module pool.

Call applyChangeSet to apply changes commited by another transaction. The integer id parameter (returned by commitAndSaveChangeSet) identifies the change set to be found in the persistent store.

After this call, this transaction's cache is synchronized with the changes from the change set.

For an example of how to use applyChangeSet, see commitAndSaveChangeSet.

Specified by:

applyChangeSet in interface Transaction

Parameters:

id - an integer representing the change set to apply to the transaction.

See Also:

Transaction.commitAndSaveChangeSet(), Transaction.removeChangeSet(int)

removeChangeSet

public void removeChangeSet(int id)

Description copied from interface: Transaction

Removes the change set that defines the changes to EntityImpls within a transaction.

This method (along with commitAndSaveChangeSet and applyChangeSet is used to synchronize the cache between root Application Module instances in an Application Module pool.

For an example of how to use removeChangeSet, see commitAndSaveChangeSet.

Specified by:

removeChangeSet in interface Transaction

Parameters:

id - an integer representing the change set to remove from the persistent store.

See Also:

Transaction.commitAndSaveChangeSet(), Transaction.applyChangeSet(int)

doPoolMessage

public ApplicationPoolSvcMsgContext doPoolMessage(ApplicationPoolSvcMsgContext ctx)

Description copied from interface: ApplicationModule

Internal use only. Applications should not use. Used by the ApplicationPool to send batch ApplicationModule requests.

Specified by:

doPoolMessage in interface ApplicationModule

setStyles

public void setStyles(java.lang.String name,
                      ClientDocument clientDocument)

Saves the Style Definitions to the Middle Tier

Specified by:

setStyles in interface ApplicationModule

Parameters:

name - The style Storage Name

clientDocument - The ClientDocument that needs to be saved

See Also:

ClientDocument

getStyles

public ClientDocument getStyles(java.lang.String name)

Gets the Style Definitions from the Middle Tier

Specified by:

getStyles in interface ApplicationModule

Parameters:

name - The style Storage Name

Returns:

clientDocument Returns the Client Document

See Also:

ClientDocument

getViewObjectNames

public java.lang.String[] getViewObjectNames()

Return the names of the ViewUsages (static and dynamic) defined in this applicationModule.

Specified by:

getViewObjectNames in interface ApplicationModule

Returns:

String[] ViewUsage names

See Also:

ApplicationModule.findViewObject(String)

getViewObjectNames

public java.lang.String[] getViewObjectNames(boolean inclLoadedOnes,
                                             boolean inclNotLoadedOnes)

Description copied from interface: ApplicationModule

Returns an array of names of the View Objects in this Application Module.

This method allows the user to control whether the returning names are those of loaded (instantiated) View Objects, or those of not yet loaded (uninstantiated) View Objects, or both. Not yet loaded View Objects would appear only if lazy loading is turned on.

Note that ApplicationModule.getViewObjectNames() is equivalent to getViewObjectNames(true, false).

If this method is called with loadedOnes = true and fromDef = true, both loaded and not-yet-loaded View Object names are returned. No duplicate name is returned. Note that loaded View Objects include dynamically created ones.

Specified by:

getViewObjectNames in interface ApplicationModule

Parameters:

inclNotLoadedOnes - if true, names of the View Objects from the Application Module definition are returned. Some of these VOs could have already been loaded and some may have not yet been loaded.

Returns:

an array of View Object names. If this Application Module contains no View Object, it returns an empty array, i.e., new String[0].

getViewDefNames

public java.lang.String[] getViewDefNames(java.lang.String packName)

Return the names of the ViewObject available in the root package.

Specified by:

getViewDefNames in interface Session

Parameters:

packName - the name of the package.

Returns:

String[] name of the ViewObject.

getAllViewDefNames

public java.lang.String[] getAllViewDefNames()

Return the names of the ViewObject available in all nested packages.

Specified by:

getAllViewDefNames in interface Session

Returns:

String[] name of the ViewObject.

getEntityDefNames

public java.lang.String[] getEntityDefNames(java.lang.String packName)

Return the names of the EntityObject available in the root package.

Specified by:

getEntityDefNames in interface Session

Parameters:

packName - the name of the package.

Returns:

String[] names of the Entities.

getAllEntityDefNames

public java.lang.String[] getAllEntityDefNames()

Return the names of the EntityObject available in all nested packages.

Specified by:

getAllEntityDefNames in interface Session

Returns:

String[] names of the Entities.

createViewObject

public ViewObject createViewObject(java.lang.String voName,
                                   java.lang.String vDefName)

Create a ViewUsage using the name of a ViewObject class.

Specified by:

createViewObject in interface ApplicationModule

Parameters:

voName - name of the ViewObject class

vDefName - the name of the View Object definition from which the new View Object is to be created. It must be a fully qualified name (including the package name).

Returns:

true is succeeded

createComponentObject

public ComponentObject createComponentObject(java.lang.String coName,
                                             java.lang.String cDefName)

Create a ComponentUsage using the name of a ComponentObject class.

Specified by:

createComponentObject in interface ApplicationModule

Parameters:

coName - name that will be given to the ComponentUsage

Returns:

true is succeeded

createViewObjectFromQueryClauses

public ViewObject createViewObjectFromQueryClauses(java.lang.String voName,
                                                   java.lang.String eoName,
                                                   java.lang.String selectClause,
                                                   java.lang.String fromClause,
                                                   java.lang.String whereClause,
                                                   java.lang.String orderByClause)

Description copied from interface: ApplicationModule

Creates an View Object in this Application Module from an Entity Object and additional SQL clauses. The returning View Object will have that Entity Object as its sole Entity Object base. This method cannot create a View Object that joins two Entity Objects. The View Object's attributes will be those that are mapped to the Entity Object's attributes.

For example, suppose we have an Entity Object named Emp in a package named package1. The following code block creates a View Object using this method:

    ViewObject vo = am.createViewObjectFromQueryClauses("MyVO",
         "package1.Emp",      // Fully qualified EO name
         "E.ENAME as EmpName, E.EMPNO as EmpNo",  // select clause
         "EMP E",             // from clause
         "E.DEPTNO = 10",     // where clause
          null);              // order by clause
 

Internally, this methods create a temporary View Object definition from the Entity Object and sets the select, from, where, and order-by clauses of the View Definition. Then, it uses that View Object definition to create the View Object.

Specified by:

createViewObjectFromQueryClauses in interface ApplicationModule

Parameters:

eoName - the name of the Entity Object from which the new View Object is to be derived.

selectClause - a SQL statement SELECT clause. The name or alias of each column must match the name of the corresponding Entity Object's attribute. In the above example code, "ENAME" and "EMPNO" are database column names, and "EmpName" and "EmpNo" are Entity Object's attribute names.

fromClause - a SQL statement FROM clause.

whereClause - a SQL statement WHERE clause. If null no where clause is established, i.e., all rows from the database table/view are retrieved.

orderByClause - a SQL statement ORDER-BY clause. If null no order-by clause is established.

Returns:

a new View Object.

createViewObjectFromQueryStmt

public ViewObject createViewObjectFromQueryStmt(java.lang.String voName,
                                                java.lang.String sqlStatement)

Create a ViewUsage using a SQL statement.

Specified by:

createViewObjectFromQueryStmt in interface ApplicationModule

Parameters:

sqlStatement - SQL statement of the ViewRow

Returns:

true is succeeded

executeCommand

public int executeCommand(java.lang.String command)

Description copied from interface: Transaction

Executes a SQL command using a JDBC Statement under the current transaction. Applications should use this method to execute application-specific JDBC statements.

This method provides a way of bypassing the framework to query the database directly. Internally, the method passes the specified SQL command to a statement on the JDBC connection and executes it.

The following code example uses executeCommand. The SQL string is designed to update the EMP table. This example passes the string to executeCommand, then prints a message to report how many rows were actually updated.

 public static void demoUpdateColumn(ApplicationModule appMod) {
     String sqlStr = "UPDATE EMP " +
                     "SET MGR=7007 " +
                     "WHERE MGR=7698 ";

     int n = appMod.getTransaction().executeCommand(sqlStr);
     System.out.println("Updated " + n + " rows.");
   }
 

Be careful when using executeCommand, because it will execute any valid SQL statement. For example, you could perform an operation like the following DDL command:

 appMod.getTransaction().executeCommand("DROP TABLE MYTEMPTABLE");
 

A pending database transaction could be committed inadvertently due to the implicit commit performed by DDL operations, as well as having any row locks released.

Specified by:

executeCommand in interface Transaction

Parameters:

command - a valid SQL statement.

Returns:

the number of rows affected.

dumpQueryResult

public java.lang.String dumpQueryResult(java.lang.String query,
                                        java.lang.String dumpClassName,
                                        java.lang.String[] data)

Description copied from interface: Transaction

Writes the result of the query to a (potentially very long) string. It takes three parameters: the first is the SQL query statement. The second is the class that dumps the result to a string. This class must implement the oracle.jbo.server.QueryDump interface. The implementation of this class decides what to do with the third, data parameter (which can be null). This is a utility method for testing and debugging queries and applications.

The following code example uses dumpQueryResult.

 public static void demoSimpleFetch(ApplicationModule appMod) {
       // Define and execute a simple SQL statement.
       String sqlStr = "SELECT Emp.ename FROM EMP Emp ";
       // dumpQueryResult is a utility method for testing queries.
       String result = appMod.getTransaction().dumpQueryResult(sqlStr,
                                    "oracle.jbo.server.QueryDumpTab",
                                      null);

 System.out.println(sqlStr);
 System.out.println(result);  }
 

Specified by:

dumpQueryResult in interface Transaction

Parameters:

query - the SQL query statement.

dumpClassName - the class that dumps the result to a string.

data - an array of data items.

getEstimatedRowCount

public long getEstimatedRowCount(int rsId)

getRowCount

public int getRowCount(int rsId)

getFetchedRowCount

public int getFetchedRowCount(int rsiId)

getEntityAssociationDefNames

public java.lang.String[] getEntityAssociationDefNames(java.lang.String packName)

Description copied from interface: Session

Gets the names of the entity association definitions defined in a package.

Specified by:

getEntityAssociationDefNames in interface Session

Parameters:

packName - the name of the package.

Returns:

String[] an array of EntityAssociationDef names.

getAllEntityAssociationDefNames

public java.lang.String[] getAllEntityAssociationDefNames()

Description copied from interface: Session

Gets the names of the entity association definitions defined in all packages.

Specified by:

getAllEntityAssociationDefNames in interface Session

Returns:

String[] an array of EntityAssociationDef names.

getViewLinkDefNames

public java.lang.String[] getViewLinkDefNames(java.lang.String packName)

Description copied from interface: Session

Gets the names of the View Link definitions defined in a package.

Specified by:

getViewLinkDefNames in interface Session

Parameters:

packName - the name of the package.

Returns:

String[] an array of ViewLinkDef names.

getAllViewLinkDefNames

public java.lang.String[] getAllViewLinkDefNames()

Description copied from interface: Session

Gets the names of the View Link definitions defined in all packages.

Specified by:

getAllViewLinkDefNames in interface Session

Returns:

String[] an array of ViewLinkDef names.

getViewLinkNames

public java.lang.String[] getViewLinkNames()

Description copied from interface: ApplicationModule

Returns an array of the names of the View Links that are currently loaded within this Application Module.

Example code:

    String[] vlNames = am.getViewLinkNames();

    // If you want to retrieve all currently loaded View Links
    ViewLink[] vls = new ViewLink[vlNames.length];

    for (int i = 0; i < vlNames.length; i++)
    {
       vls[i] = am.findViewLink(vlNames[i]);
    }
 

If you need names of View Objects that are not yet loaded, use ApplicationModule.getViewLinkNames(boolean, boolean).

Specified by:

getViewLinkNames in interface ApplicationModule

Returns:

an array of View Link names. If this Application Module contains no View Link, it returns an empty array, i.e., new String[0].

See Also:

ApplicationModule.findViewLink(String)

getViewLinkNames

public java.lang.String[] getViewLinkNames(boolean inclLoadedOnes,
                                           boolean inclNotLoadedOnes)

Description copied from interface: ApplicationModule

Returns an array of names of the View Links in this Application Module.

This method allows the user to control whether the returning names are those of loaded (instantiated) View Links, or those of not yet loaded (uninstantiated) View Links, or both. Not yet loaded View Links would appear only if lazy loading is turned on.

Note that ApplicationModule.getViewLinkNames() is equivalent to getViewLinkNames(true, false).

If this method is called with loadedOnes = true and fromDef = true, both loaded and not-yet-loaded View Link names are returned. No duplicate name is returned. Note that loaded View Links include dynamically created ones.

Specified by:

getViewLinkNames in interface ApplicationModule

Parameters:

inclNotLoadedOnes - if true, names of the View Links from the Application Module definition are returned. Some of these VLs could have already been loaded and some may have not yet been loaded.

Returns:

an array of View Link names. If this Application Module contains no View Link, it returns an empty array, i.e., new String[0].

findViewLink

public ViewLink findViewLink(java.lang.String viewLinkName)

Description copied from interface: ApplicationModule

Finds the named View Link. The View Link name passed in (vlName) may or may not be qualified with the name of the containing Application Module. If it is, the View Link name is said to be an AM-qualified View Link name. If not, the name is said to be an unqualified View Link name.

An AM-qualified name is a multi-part name (separated by dots). The last part of the name is the View Link name (View Link part of the name). All preceding parts consistitute the name of the Application Module that contains the View Link. For an AM-qualified name, findViewLink() first locates the containing Application Module using the Application Module name. In fact, it uses ApplicationModule.findApplicationModule(String) to find the Application Module. Thus, the Application Module name in an AM-qualified View Link name may be relative or absolute Application Module name. See findApplicationModule() discussions on absolute and relative Application Module names. Once the Application Module is found, the View Link part is used to find the View Link in that Application Module.

If the View Link name is unqualified, the search for the View Link is made on this Application Module.

For example, suppose we have the following containership of nested Application Modules and View Links:

    Root (root Application Module)
       ChildAM1
          ViewLinkA
          GrandChildAM1_1
             ViewLinkB
          GrandChildAM1_2
             GreatGrandChildAM1_2_1
                ViewLinkC
       ChildAM2
          GrandChildAM2_1
             ViewLinkD
 

ChildAM1.findViewLink("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewLinkC") will succeed (using relative Application Module name).

ChildAM2.findViewLink("Root.ChildAM1.GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewLinkC") will succeed (using absolute Application Module name) and return the same View Link as ChildAM1.findViewLink("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewLinkC").

Both these are AM-qualified name cases.

GrandChildAM2_1.findViewLink("ViewLinkD") will succeed. This is is an unqualified name case.

For View Link searching, findViewLink() makes no distinction between View Links included the Application Module during design time and those created programmatically during runtime.

Example code:

    ViewLink vl = am.findViewLink("MyVL");
 

Specified by:

findViewLink in interface ApplicationModule

Parameters:

viewLinkName - the name of the View Link.

Returns:

the View Link. null if the View Link is not found.

See Also:

ApplicationModule.findApplicationModule(String), ApplicationModule.findViewObject(String)

createViewLink

public ViewLink createViewLink(java.lang.String viewLinkName,
                               java.lang.String viewLinkDefName,
                               ViewObject master,
                               ViewObject detail)

Description copied from interface: ApplicationModule

Creates a View Link in this Application Module from the View Link definition. The View Link definition is identified by the defName parameter.

master and detail identifies two View Objects that will linked by this new View Link.

For example, assume that during design time, the user used the Design Time View Object Wizard to create two View Objects, DeptView and EmpView inside of a package named package1. Then, assume that the user invoked the View Link Wizard to create a View Link definition (in the same package) named DeptEmpViewLink, that correlates the DeptNo attribute of DeptView to the DeptNo attribute of EmpView.

Given these, the user can use the code block like the following to create in this Application Module (represented by am) two View Objects and a View Link programmatically (during runtime):

    ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
    ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");

    ViewLink vl = am.createViewLink("MyDeptEmpLink", "package1.DeptEmpViewLink",
                                    voDept, voEmp);
 

This will set up a master-detail relationship between voDept and voEmp. Whenever voDept's currency moves, voEmp's result set will be refreshed to show employees that work in the department.

This method verifies that the View Objects passed in match the View Link definition. Specifically, in the above example, createViewLink() checks to ensure that the master (voDept) is an instance of package1.DeptView and that the detail (voEmp) is an instance of package1.EmpView. If match fails, an error (InvalidParamException) is reported, as the user tried to set up a View Link between two View Objects where the View Link definition does not match the View Link definitions of master and detail.

One exception to this match rule is that createViewLink() allows the user to reverse the View Link direction. Thus, in the above example, the following would have succeeded:

    ViewLink vl = am.createViewLink("MyEmpDeptLink", "package1.DeptEmpViewLink",
                                    voEmp, voDept);
 

Note that in the above code block, voEmp is the master and voDept is the detail. The View Link definition is used in the reverse direction.

Specified by:

createViewLink in interface ApplicationModule

Parameters:

viewLinkName - the name to be assigned to the View Link. If null, a system generated name is assigned.

viewLinkDefName - the name of the link definition from which the new View Link is to be created. It must be a fully qualified name (including the package name).

master - the View Object that is to play the role of master.

detail - the View Object that is to play the role of detail.

Returns:

a new View Link.

See Also:

ApplicationModule.createViewObject(String, String)

createViewLinkFromEntityAssocName

public ViewLink createViewLinkFromEntityAssocName(java.lang.String viewLinkName,
                                                  java.lang.String entityAssocName,
                                                  ViewObject master,
                                                  ViewObject detail)

Description copied from interface: ApplicationModule

Creates a View Link in this Application Module from an Entity Association. The returning View Link will use the Entity Association's definition to build a link between the two Viwe Objects.

For example, suppose we have two Entity Objects in package package1: Dept and Emp. An Entity Association DeptEmpAssoc is created between the two Entity Objects relating the Deptno attribute. Two View Objects are defined on these Entity Objects, DeptView and EmpView.

The following code creates two View Objects in this Application Module and link them, using DeptEmpAssoc:

    ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
    ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");

    ViewLink vl = am.createViewLinkFromEntityAssocName("MyDeptEmpLink",
                        "package1.DeptEmpAssoc",
                        voDept, voEmp);
 

This will set up a master-detail relationship between voDept and voEmp. Whenever voDept's currency moves, voEmp's result set will be refreshed to show employees that work in the department.

Internally, this method creates a temporary View Link definition from the Entity Association and uses it to create the View Link.

This method verifies that the View Objects passed in match the Entity Association definition. Specifically, in the above example, createViewLinkFromEntityAssocName() checks to ensure that the master (voDept) uses the Dept Entity Object as one of its Entity bases and the detail (voEmp) uses the Emp Entity Object as one of its Entity bases. If match fails, an error (InvalidParamException) is reported, as the user tried to set up a View Link between two View Objects where the Entity Association is unable to relate the two View Objects.

The primary difference between ApplicationModule.createViewLink(String, String, ViewObject, ViewObject) and createViewLinkFromEntityAssocName is that the former requires the View Link Definition name, and the latter requires the Entity Association name.

Specified by:

createViewLinkFromEntityAssocName in interface ApplicationModule

Parameters:

viewLinkName - the name to be assigned to the View Link. If null, a system generated name is assigned.

entityAssocName - the name of the Entity Association from which the new View Link is to be derived. It must be a fully qualified name (including the package name).

master - the View Object that is to play the role of master.

detail - the View Object that is to play the role of detail.

Returns:

a new View Link.

See Also:

ApplicationModule.createViewObject(String, String)

createViewLinkBetweenViewObjects

public ViewLink createViewLinkBetweenViewObjects(java.lang.String viewLinkName,
                                                 java.lang.String accessorName,
                                                 ViewObject master,
                                                 AttributeDef[] srcAttrs,
                                                 ViewObject detail,
                                                 AttributeDef[] destAttrs,
                                                 java.lang.String assocClause)

Description copied from interface: ApplicationModule

Creates a View Link in this Application Module. This View Link is not created from either a View Link definition or an Entity Association. Rather, all required information are passed as parameters, and the View Link is created based on the info. The user must supply the following info:

• Master View Object - the View Object that is to play the role of master.
• Detail View Object - the View Object that is to play the role of detail.
• Source attributes - One or more attributes from the master View Object to be related to the destination attributes.
• Destination attributes - One or more attribute from the detail View Object to be related to the source attributes. Note that the source/destination attribute arrays must have the same number of elements.
• View Link accessor name - Optionally, the user can supply a name by which the related detail Row Set can be retrieved as an attribute. More on this below...
• Association clause - The user can override the default association clause to be generated by BC4J by supply his custom clause.

For example, suppose we have two Views Objects in package package1: DeptView and EmpView. Each of them has an attribute named Deptno.

The following code creates two View Objects in this Application Module and link them by the Deptno attribute:

    ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
    ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");

    AttributeDef[] deptLinkAttrs = new AttributeDef[] { voDept.findAttributeDef("Deptno") };
    AttributeDef[] empLinkAttrs = new AttributeDef[] { voEmp.findAttributeDef("Deptno") };

    ViewLink vl = am.createViewLinkFromEntityAssocName("MyDeptEmpLink",
                        "Employees",
                        voDept, deptLinkAttrs,
                        voEmp, empLinkAttrs,
                        null);
 

This will set up a master-detail relationship between voDept and voEmp. Whenever voDept's currency moves, voEmp's result set will be refreshed to show employees that work in the department.

Using the Association Clause
This View Link will generate a SQL clause like EMP.DEPTNO=? on voEmp. The Deptno value of the current row in voDept (master) is bound into the bind variable ('?'). This results in limiting query on voEmp to employees whose Deptno equals the current Dept's Deptno.

By supplying a non-null association clause (the last parameter), the user can override the default SQL clause and replace it with his. For example, if he wishes to include only employees whose JOB is ANALYST, he can supply the following assocClause: EMP.DEPTNO=? AND EMP.JOB='ANALYST'.

Using the Accessor Name
If the user supplies a non-null accessorName (the second parameter), a dynamic attribute is added to master View Object which allows the user retrieve related rows from a master row.

In the above code example, a dynamic attribute "Employees" is added to voDept, such that if the user retrieve that attribute on a row the came from voDept, it will return a Row Set of Emp's that are related to that row.

The code example below retrieves all rows from voDept and for each Dept row, retrieves its employees by using the "Employees" attribute and prints their names.

    Row deptRow;

    while ((deptRow = voDept.next()) != null)
    {
       System.out.println("Dept: " + deptRow.getAttribute("Dname"));

       RowSet emps = (RowSet) deptRow.getAttribute("Employees");
       Row empRow;

       while ((empRow = emps.next()) != null)
       {
          System.out.println("  Emp: " + empRow.getAttribute("Ename"));
       }
    }
 

Specified by:

createViewLinkBetweenViewObjects in interface ApplicationModule

Parameters:

viewLinkName - the name to be assigned to the View Link. If null, a system generated name is assigned.

accessorName - the name to be given to the dynamic attribute to be added to master View Object. Given a row from the master View Object, the user can retrieve the attribute of this name to get a Row Set of related rows from the detail View Object. See the above discussions for more info. If null, no dynamic attribute is added.

master - the View Object that is to play the role of master.

srcAttrs - an array of attributes from master View Object to be related to detail.

detail - the View Object that is to play the role of detail.

destAttrs - an array of attributes from detail View Object to be related to master.

assocClause - a custom association clause. See the above discussions for more info. If null, system generated SQL clause will be used.

Returns:

a new View Link.

See Also:

ApplicationModule.createViewObject(String, String), StructureDef.findAttributeDef(String), RowIterator.next(), AttributeList.getAttribute(String)

findViewObject

public ViewObject findViewObject(java.lang.String voName)

Description copied from interface: ApplicationModule

Finds the named View Object. The View Object name passed in (voName) may or may not be qualified with the name of the containing Application Module. If it is, the View Object name is said to be an AM-qualified View Object name. If not, the name is said to be an unqualified View Object name.

An AM-qualified name is a multi-part name (separated by dots). The last part of the name is the View Object name (View Object part of the name). All preceding parts consistitute the name of the Application Module that contains the View Object. For an AM-qualified name, findViewObject() first locates the containing Application Module using the Application Module name. In fact, it uses ApplicationModule.findApplicationModule(String) to find the Application Module. Thus, the Application Module name in an AM-qualified View Object name may be relative or absolute Application Module name. See findApplicationModule() discussions on absolute and relative Application Module names. Once the Application Module is found, the View Object part is used to find the View Object in that Application Module.

If the View Object name is unqualified, the search for the View Object is made on this Application Module.

For example, suppose we have the following containership of nested Application Modules and View Objects:

    Root (root Application Module)
       ChildAM1
          ViewObjectA
          GrandChildAM1_1
             ViewObjectB
          GrandChildAM1_2
             GreatGrandChildAM1_2_1
                ViewObjectC
       ChildAM2
          GrandChildAM2_1
             ViewObjectD
 

ChildAM1.findViewObject("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewObjectC") will succeed (using relative Application Module name).

ChildAM2.findViewObject("Root.ChildAM1.GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewObjectC") will succeed (using absolute Application Module name) and return the same View Object as ChildAM1.findViewObject("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewObjectC").

Both these are AM-qualified name cases.

GrandChildAM2_1.findViewObject("ViewObjectD") will succeed. This is is an unqualified name case.

For View Object searching, findViewObject() makes no distinction between View Objects included the Application Module during design time and those created programmatically during runtime.

Example code:

    ViewObject vo = am.findViewObject("MyVO");
 

Specified by:

findViewObject in interface ApplicationModule

Parameters:

voName - the name of the View Object.

Returns:

the View Object. null if the View Object is not found.

See Also:

ApplicationModule.findApplicationModule(String), ApplicationModule.findViewLink(String)

findComponentObject

public ComponentObject findComponentObject(java.lang.String coName)

Description copied from interface: ApplicationModule

Finds the named Component Object. See ApplicationModule.createComponentObject(String, String) for explanation of BC4J's support for custom Component Objects.

See ApplicationModule.findViewObject(String) for explanation on AM-qualified names and unqualified names.

Specified by:

findComponentObject in interface ApplicationModule

Parameters:

coName - the name of the Component Object.

Returns:

the Component Object. null if the Component Object is not found.

See Also:

ApplicationModule.findApplicationModule(String)

remove

public void remove()

Description copied from interface: ComponentObject

Deletes this component.

Specified by:

remove in interface ComponentObject

getDefName

public java.lang.String getDefName()

Retrieve the application module definition name.

Specified by:

getDefName in interface ComponentObject

Returns:

name of the application module definition

getDefFullName

public java.lang.String getDefFullName()

Retrieve the application module definition's full name.

Specified by:

getDefFullName in interface ComponentObject

Returns:

full name of the application module definition

getName

public java.lang.String getName()

Retrieve the name of the particular instance of an object (instance name)

Specified by:

getName in interface ClientComponentObject

Returns:

name of the object

getFullName

public java.lang.String getFullName()

Description copied from interface: ComponentObject

Retrieves the fully-qualified name of this component.

Specified by:

getFullName in interface ClientComponentObject

fetchAttributeProperties

public void fetchAttributeProperties(java.lang.String[] voNames,
                                     java.lang.String[][] attrNames,
                                     LocaleContext locale)

Description copied from interface: ApplicationModule

Fetches all custom properties for the given list of attributes for the named ViewObjects in this application module over to the remote client objects in one network roundtrip. This method is a no-op in when this application module is deployed in local-mode.

For clients like JClient applications, this method helps in downloading all the attribute properties over to the client side in one roundtrip so that startup of these applications are more performant. Calls to properties methods like getFormat(), getLabel(), etc. on the Attribute definition then, does not go over the network boundary for the attributes that are included in the parameter list.

Specified by:

fetchAttributeProperties in interface ApplicationModule

getProperties

public java.util.Hashtable getProperties()

Override PropertyHelper.getProperties

Specified by:

getProperties in interface Properties

Specified by:

getProperties in class PropertiesHelper

setProperty

public void setProperty(java.lang.String hintName,
                        java.lang.Object hintValue)

Overrides:

setProperty in class PropertiesHelper

refreshProperty

public java.lang.Object refreshProperty(java.lang.String hintName)

Description copied from interface: Properties

Retrieves the specified property, if it exists. If the application running in a 3 tier environment, it retrieves the property from the middle-tier server, refreshing the value on the client side. If the application is running in a 2 tier environment, it is equivalent to getProperty.

Specified by:

refreshProperty in interface Properties

Overrides:

refreshProperty in class PropertiesHelper

writeRowSetXMLWithMap

public Node writeRowSetXMLWithMap(int rsId,
                                  long options,
                                  com.sun.java.util.collections.HashMap map)

writeRowXMLWithMap

public Node writeRowXMLWithMap(int rsiId,
                               RowImpl row,
                               long options,
                               com.sun.java.util.collections.HashMap map)

writeRowXML

public Node writeRowXML(int rsiId,
                        RowImpl row,
                        int depthCount,
                        long options)

readRowXML

public void readRowXML(int rsiId,
                       RowImpl row,
                       Element elem,
                       int depthCount)

writeRowSetXML

public Node writeRowSetXML(int rsId,
                           int depthCount,
                           long options)

readRowSetXML

public void readRowSetXML(int rsId,
                          Element elem,
                          int depthCount)

getRowSets

protected RowSet[] getRowSets(int voId)

getRowSetIterators

protected RowSetIterator[] getRowSetIterators(int rsId)

createWorkerApplicationModule

public ApplicationModule createWorkerApplicationModule(java.lang.Object sessionCookie)

Specified by:

createWorkerApplicationModule in interface WSApplicationModuleMarshaller

getAppModuleRequestHandler

public AppModuleRequestHandler getAppModuleRequestHandler()

Specified by:

getAppModuleRequestHandler in interface WSApplicationModuleMarshaller

syncWorkingSet

public void syncWorkingSet(WSApplicationModuleImpl wsAM)

Specified by:

syncWorkingSet in interface WSApplicationModuleMarshaller

finishSyncWorkingSet

public void finishSyncWorkingSet(WSApplicationModuleImpl wsAM,
                                 boolean isEndOfSvcMsg)

Specified by:

finishSyncWorkingSet in interface WSApplicationModuleMarshaller

sendWorkingSetRequests

public ServiceMessage sendWorkingSetRequests(java.lang.String reqName,
                                             WSApplicationModuleImpl wsAM,
                                             ServiceMessage msg)

Specified by:

sendWorkingSetRequests in interface WSApplicationModuleMarshaller

getResponseName

public java.lang.String getResponseName()

Specified by:

getResponseName in interface WSApplicationModuleMarshaller

getRemoteObjectId

public int getRemoteObjectId(java.lang.Object obj)

Specified by:

getRemoteObjectId in interface WSApplicationModuleMarshaller

addResponse

public void addResponse(java.io.Serializable res)

Specified by:

addResponse in interface WSApplicationModuleMarshaller

setDataModelRefresh

public void setDataModelRefresh(boolean b)

Specified by:

setDataModelRefresh in interface WSApplicationModuleMarshaller

setVOProperty

public void setVOProperty(int voId,
                          java.lang.String hintName,
                          java.lang.Object hintValue)

refreshVOProperty

public java.lang.Object refreshVOProperty(int voId,
                                          java.lang.String hintName)

clearEntityCache

public void clearEntityCache(java.lang.String entityName)

Description copied from interface: Transaction

Clears the cache of the specified Entity Object. A value of null clears the caches of all Entities. If a View Object uses the Entity Object, the View Object's cache will be cleared as well.

Specified by:

clearEntityCache in interface Transaction

Parameters:

entityName - the name of the entity whose cache is to be cleared. If null, caches for all entities are cleared.

clearVOCaches

public void clearVOCaches(java.lang.String entityName,
                          boolean recurse)

Description copied from interface: ApplicationModule

Clears the View Object cache for all View Objects that use an Entity Object identified by entityName. This method finds all View Objects that use the Entity, then calls ViewObject.clearCache() on each View Object.

If entityName is null, then the caches of all View Objects in the Application Module are cleared. If recurse is true, it recurses into nested Application Modules.

Specified by:

clearVOCaches in interface ApplicationModule

Parameters:

entityName - fully qualified name of the Entity object. If null all View Object caches are cleared.

recurse - a flag indicating whether to recurse into nested Application Modules.

processPiggyback

protected void processPiggyback(byte[] pb)

processServiceMessage

protected com.sun.java.util.collections.ArrayList processServiceMessage(ServiceMessage svcMsg)

handleException

public void handleException(java.lang.Exception ex,
                            boolean lastEntryInPiggyback)

Description copied from interface: JboExceptionHandler

Catches an exception thrown by the middle tier.

Specified by:

handleException in interface JboExceptionHandler

Parameters:

ex - an exception.

lastEntryInPiggyback - true if ex is the last of a batch of exceptions and warnings generated by a transaction.

handleWarning

public void handleWarning(JboWarning warn)

Description copied from interface: JboExceptionHandler

Catches a warning thrown by the middle tier.

Specified by:

handleWarning in interface JboExceptionHandler

Parameters:

warn - a warning message.

finishedProcessingPiggyback

public void finishedProcessingPiggyback(java.lang.Exception[] exArr)

Specified by:

finishedProcessingPiggyback in interface JboExceptionHandler

getExceptionHandler

public JboExceptionHandler getExceptionHandler()

Specified by:

getExceptionHandler in interface ApplicationModule

setExceptionHandler

public void setExceptionHandler(JboExceptionHandler hndlr)

Description copied from interface: ApplicationModule

Sets the exception handler for this Application Module. An exception handler must implement the JboExceptionHandler interface.

JboExceptionHandler handle exceptions (java.lang.Exception) and warnings (JboWarning). In 2 tier mode, the handler will only see warnings but no exception. In 2 tier mode, Exceptions are thrown through the normal Java throw mechanism. They should be handled through catch blocks. For warnings, no throw/catch mechanism is available. The handler must process them.

In 3 tier mode, the handler may have to process exceptions in addition to warnings. When a method call is marshalled from the client tier into the middle tier, the middle tier processing of the method may result in more than one exceptions. All these exceptions are caught by the marshalling code and brought back to the client tier. As Java's throw mechanism allows throwing of only one exception, these multiple exceptions cannot be processed through Java throw. Thus, for each of these exceptions, a call is made to handler's handleException(), so that the handler can process it.

Specified by:

setExceptionHandler in interface ApplicationModule

Parameters:

hndlr - an exception handler.

addWarning

public void addWarning(JboWarning warn)

Description copied from interface: ApplicationModule

Adds a warning message. In 2 tier mode, the warning is passed to this method is sent to the exception handler immediately if an exception handler is present (exception handler is specified through a call to ApplicationModule.setExceptionHandler(JboExceptionHandler)). This is done through a call to JboExceptionHandler.handleWarning(JboWarning).

In 3 tier mode, the warnings that came to this Application Module through calls to addWarning() in the middle tier are "chained" until the middle tier processing completes. They are brought to the client at the end of middle tier processing, and, for each warning, a call is made to JboExceptionHandler.handleWarning(JboWarning) if an exception handler is present.

Specified by:

addWarning in interface ApplicationModule

Parameters:

warn - warning message.

hasPendingDataPosts

public boolean hasPendingDataPosts()

Specified by:

hasPendingDataPosts in interface WSApplicationModuleMarshaller

setLockingMode

public void setLockingMode(int mode)

Description copied from interface: Transaction

Sets the preferred locking mode for this Transaction. The possible values are:

• LOCK_NONE - Row locking mode is Manual.
• LOCK_PESSIMISTIC (default) - Row locking mode is Automatic and Pessimistic.
• LOCK_OPTIMISTIC - Row locking mode is Automatic and Optimistic.

Changing the locking mode affects only subsequent locks. Current locks are not affected.

Specified by:

setLockingMode in interface Transaction

Parameters:

mode - one of LOCK_PESSIMISTIC, LOCK_OPTIMISTIC or LOCK_NONE.

getLockingMode

public int getLockingMode()

Description copied from interface: Transaction

Returns the preferred locking mode for this Transaction. For example:

 am.getTransaction().getLockingMode();
 

The possible return values are:

• LOCK_NONE Row locking mode is Manual.
• LOCK_PESSIMISTIC (default) - Row locking mode is Automatic and Pessimistic.
• LOCK_OPTIMISTIC - Row locking mode is Automatic and Optimistic.

If not set by setLockingMode, the locking mode defaults to LOCK_PESSIMISTIC.

Specified by:

getLockingMode in interface Transaction

Returns:

an integer representing the preferred locking mode. The values can be LOCK_NONE, LOCK_PESSIMISTIC (default), or LOCK_OPTIMISTIC.

setBundledExceptionMode

public void setBundledExceptionMode(boolean flag)

Description copied from interface: Transaction

Set this transaction into bundled exception mode. In this mode, all exceptions thrown during updates to rows will be cached by the entity-cache. However when the rows are validated either by explicit validation call or when the transaction is committed, these exceptions will be thrown bundled in a RowValException. When in bundledException mode, validation code in setXXX methods on the Entity will be executed and if a ValidationException is thrown from these methods, they're cached by the Entity and thrown later as a detail of RowValException when the Entity is eventually validated.

Specified by:

setBundledExceptionMode in interface Transaction

isBundledExceptionMode

public final boolean isBundledExceptionMode()

Specified by:

isBundledExceptionMode in interface Transaction

setClearCacheOnCommit

public void setClearCacheOnCommit(boolean val)

Description copied from interface: Transaction

Sets the value of the flag indicating whether all Entity Object caches will be cleared after the transaction is committed.

The initial value of this flag is retrieved from the Application Module definition of the root Application Module (an XML attribute value named "ClearCacheOnCommit" in the Application Module definition's XML file). If the Application Module definition does not contain the initial value, the default value is false, i.e., the caches are kept after commit.

The user can override the value of this flag for this Transaction by calling this method. Calling this method does not affect the initial value in the Application Module definition.

Specified by:

setClearCacheOnCommit in interface Transaction

Parameters:

val - the new value of the clear-cache-on-commit flag. true indicates that the Entity Object caches will be cleared after commit.

See Also:

Transaction.isClearCacheOnCommit()

isClearCacheOnCommit

public boolean isClearCacheOnCommit()

Description copied from interface: Transaction

Returns the flag indicating whether all Entity Object caches will be cleared after the transaction is committed.

After the transaction is committed, the value of this flag is used to determine whether the Entity Object caches are cleared or not. If this flag value is false, the cache contents are kept. In this case, the cache may contain data that is stale in that it does not match the newest data (changes made by another user and committed).

If this flag is true, the caches are cleared after the transaction is committed. When the user brings in data by traversing row collection, the latest data from the database will be brought into Entity caches.

Specified by:

isClearCacheOnCommit in interface Transaction

Returns:

the current value of clear-cache-on-commit flag.

See Also:

RowSet.executeQuery(), Transaction.setClearCacheOnCommit(boolean val)

setClearCacheOnRollback

public void setClearCacheOnRollback(boolean val)

Description copied from interface: Transaction

Sets the value of the flag indicating whether all Entity Object caches will be cleared after the transaction is rolled back.

The initial value of this flag is retrieved from the Application Module definition of the root Application Module (an XML attribute value named "ClearCacheOnRollback" in the Application Module definition's XML file). If the Application Module definition does not contain the initial value, the default value is true, i.e., the caches are cleared after rollback.

The user can override the value of this flag for this Transaction by calling this method. Calling this method does not affect the initial value in the Application Module definition.

Specified by:

setClearCacheOnRollback in interface Transaction

Parameters:

val - the new value of the clear-cache-on-roll-back flag. true indicates that the Entity Object caches will be cleared after rollback, and will be refreshed with new data from the database.

See Also:

Transaction.isClearCacheOnRollback()

isClearCacheOnRollback

public boolean isClearCacheOnRollback()

Description copied from interface: Transaction

Returns the flag indicating whether all Entity Object caches will be cleared after the transaction is rolled back.

After the transaction is rolled back, the value of this flag is used to determine whether the Entity Object caches are cleared or not. If this flag value is false, the cache contents are kept. In this case, the cache may contain data that is not in sync with database in that uncommitted changes made this by user (before the transaction was rolled back) will be kept.

If this flag is true, the caches are cleared after the transaction is rolled back. When the user brings in data by traversing row collection, the latest data from the database will be brought into Entity caches.

Specified by:

isClearCacheOnRollback in interface Transaction

Returns:

the current value of clear-cache-on-roll-back flag.

See Also:

RowSet.executeQuery(), Transaction.setClearCacheOnRollback(boolean val)

loadPackage

public void loadPackage(java.lang.String packageName)

Description copied from interface: Session

Loads a package that may be browsed for defined objects.

Specified by:

loadPackage in interface Session

Parameters:

packageName - a fully qualified package name.

createDetailRowSet

protected RowSet createDetailRowSet(int rsiId,
                                    java.lang.String rsName,
                                    java.lang.String vlDefName)

Create a detail RowSet (ViewObject) using the name of a ViewObject class.

Returns:

true is succeeded

getDetailRowSets

protected RowSet[] getDetailRowSets(int rsiId)

getPiggyback

protected byte[] getPiggyback()

getServiceMessage

protected ServiceMessage getServiceMessage()

getViewObjectId

protected int getViewObjectId(ViewObject vo)

toEmpty

protected java.lang.String toEmpty(java.lang.String s)

marshal

public java.lang.Object marshal(java.lang.Object obj)

Specified by:

marshal in interface ObjectMarshaller

marshalForActivate

public java.lang.Object marshalForActivate(java.lang.Object obj)

Specified by:

marshalForActivate in interface WSApplicationModuleMarshaller

unMarshal

public java.lang.Object unMarshal(java.lang.Object obj)

Specified by:

unMarshal in interface ObjectMarshaller

isCustomMarshalled

public boolean isCustomMarshalled(java.lang.Object obj)

Specified by:

isCustomMarshalled in interface ObjectMarshaller

getMarshalledTypeName

public java.lang.String getMarshalledTypeName(java.lang.Object obj)

Specified by:

getMarshalledTypeName in interface ObjectMarshaller

processJboException

public void processJboException(JboException ex)

getDomainValue

public java.lang.Object getDomainValue(java.lang.String className,
                                       java.lang.String[] argTypes,
                                       java.lang.Object[] argValues)

invokeDomainMethod

public java.lang.Object invokeDomainMethod(Row row,
                                           java.lang.String attrId,
                                           boolean bringBackDomain,
                                           java.lang.String methodName,
                                           java.lang.String[] clzNames,
                                           java.lang.Object[] args)

readBlobStream

public java.lang.Object readBlobStream(int rsId,
                                       int rowId,
                                       java.lang.String attrId,
                                       int offset,
                                       int length)

readLob

public java.lang.Object readLob(int rsId,
                                int rowId,
                                java.lang.String attrId,
                                int offset,
                                int length)

readLobInternal

public java.lang.Object readLobInternal(int rsId,
                                        int rowId,
                                        java.lang.String attrId,
                                        int offset,
                                        int length,
                                        boolean isCharStream)

writeLob

public void writeLob(int rsId,
                     int rowId,
                     java.lang.String attrId,
                     byte[] data)

writeClob

public void writeClob(int rsId,
                      int rowId,
                      java.lang.String attrId,
                      char[] data)

closeLob

public void closeLob(int rsId,
                     int rowId,
                     java.lang.String attrId,
                     boolean forInput,
                     boolean isCharStream)

findRSIForEntity

public RowSetIterator findRSIForEntity(RowSetIterator[] rsis,
                                       int eRowHandle)

Description copied from interface: ApplicationModule

Finds the RowSetIterator associated with the specified Entity row handle. This method is provided to handle errors that occur during Entity post cycle.

If an error occurs while an Entity is being posted to database, the system throws a DMLException. Inside the DMLException instance is an opaque handle (an integer) identifying the Entity (an instance of EntityImpl) that caused the error.

For example, the DMLException could have been thrown because the row violated a database constraint. The client might want to give the user a chance to correct the problem by displaying the the View row that uses this Entity.

To do this, the client would "gather" all Row Set Iterators that can be used to report and fix the problem. It would then call this method, passing in the array of Row Set Iterators and the Entity row handle returned by DMLException.

Among the Row Set Iterator in the array, findRSIForEntity will pick the "best" candidate and return it to the client. The client then can use the Row Set Iterator to report the problem and give the user a chance to fix the problem.

Specified by:

findRSIForEntity in interface ApplicationModule

Parameters:

rsis - an array of RowSetIterator's to look through.

eRowHandle - the Entity row handle.

Returns:

the RowSetIterator.

See Also:

DMLException, RowSetIterator, DMLException

getTransaction

public Transaction getTransaction()

Description copied from interface: ApplicationModule

Gets this Application Module's database transaction. Note that if this method is invoked on a nested Application Module, the root Application Module's transaction is returned. This is because the transaction is shared by all Application Modules contained by the root Application Module.

If the user creates two root Application Modules, they normally do not share the transaction. To share a transaction acroos root Application Modules, the user would need to define a global transaction through JTA and have both Application Modules participate in it.

Specified by:

getTransaction in interface ApplicationModule

Returns:

the transaction.

getSession

public Session getSession()

Description copied from interface: ApplicationModule

Gets the Application Module's session. Note that if this method is invoked on a nested Application Module, the root Application Module's session is returned. This is because the session is shared by all Application Modules contained by the root Application Module.

If the user creates two root Application Modules, each has its own session.

Note that this is the same session that is passed to the ApplicationModuleImpl.activate(Session) call.

Specified by:

getSession in interface ApplicationModule

See Also:

ApplicationModuleImpl.activate(Session)

getEnvironment

public java.util.Hashtable getEnvironment()

Description copied from interface: Session

Returns the BC4J context for the session. Examples of BC4J context include the values for the BC4J properties defined in PropertyMetadata. Applications should store custom session context in the Session userdata.

Specified by:

getEnvironment in interface Session

Returns:

a hashtable of BC4J session properties

See Also:

Session.getUserData()

getUserData

public java.util.Hashtable getUserData()

Description copied from interface: Session

Returns application context for the session. Applications may store any custom session data in this Hashtable. This hashtable will be reset by {@link oracle.jbo.server.ApplicationModuleImpl.prepareSession(Session).

Specified by:

getUserData in interface Session

isRoot

public boolean isRoot()

Description copied from interface: ApplicationModule

Returns true if this Application Module is a root Application Module.

Specified by:

isRoot in interface ApplicationModule

Returns:

true if this Application Module is a root Application Module. false if this Application Module is a nested Application Module.

finishedPiggybacking

public void finishedPiggybacking()

Specified by:

finishedPiggybacking in interface ObjectMarshaller

getObjectMarshaller

public ObjectMarshaller getObjectMarshaller()

Specified by:

getObjectMarshaller in interface WSApplicationModuleMarshaller

createRef

public java.lang.Object createRef(java.lang.String structName,
                                  byte[] data)

Description copied from interface: Transaction

Internal: Applications should not use this method.

Specified by:

createRef in interface Transaction

getMaxFetchSize

public int getMaxFetchSize(int voId)

setMaxFetchSize

public void setMaxFetchSize(int voId,
                            int max)

getIterMode

public int getIterMode(int rsiId)

setIterMode

public void setIterMode(int rsiId,
                        int mode)

setRowValidation

public void setRowValidation(int rsiId,
                             boolean flag)

isRowValidation

public boolean isRowValidation(int rsiId)

getQueryOptimizerHint

public java.lang.String getQueryOptimizerHint(int voId)

setQueryOptimizerHint

public void setQueryOptimizerHint(int voId,
                                  java.lang.String hint)

getRemoteId

public int getRemoteId()

Specified by:

getRemoteId in interface ClientComponentObject

getROTEntryType

public byte getROTEntryType()

Specified by:

getROTEntryType in interface ClientComponentObject

addTransactionStateListener

public void addTransactionStateListener(TransactionStateListener target)

Add this TransactionListener to the list and notify all such listeners whenever commit and rollback occurs in this transaction.

Specified by:

addTransactionStateListener in interface Transaction

removeTransactionStateListener

public void removeTransactionStateListener(TransactionStateListener target)

Remove this transaction listener (if it exists) from this transaction.

Specified by:

removeTransactionStateListener in interface Transaction

addViewClearCacheListener

public void addViewClearCacheListener(ViewClearCacheListener target)

Specified by:

addViewClearCacheListener in interface Transaction

removeViewClearCacheListener

public void removeViewClearCacheListener(ViewClearCacheListener target)

Specified by:

removeViewClearCacheListener in interface Transaction

getLocaleContext

public LocaleContext getLocaleContext()

Description copied from interface: Session

retrieves the locale context for the session

Specified by:

getLocaleContext in interface Session

setIgnoreCustomProxies

public static void setIgnoreCustomProxies(boolean ignore)

isIgnoreCustomProxies

public static boolean isIgnoreCustomProxies()

getAMFullRef

protected ResponseValues getAMFullRef(ResponseValues handle)

createProxyApplicationModule

protected ApplicationModuleImpl createProxyApplicationModule(ResponseValues handle)

readMethodResponse

protected java.lang.Object readMethodResponse(java.lang.String methodName,
                                              ServiceMessage sm)

findOrCreateDataCollector

public DataCollector findOrCreateDataCollector(java.lang.Object obj)

Specified by:

findOrCreateDataCollector in interface ObjectMarshaller

riGetApplicationModuleInfo

public ResponseValues riGetApplicationModuleInfo()

Specified by:

riGetApplicationModuleInfo in interface AppModuleRequestHandler

riRemove

public void riRemove()

Specified by:

riRemove in interface AppModuleRequestHandler

doMessage

public ServiceMessage doMessage(ServiceMessage svcMsg)

Specified by:

doMessage in interface AppModuleRequestHandler

riInvokeExportedMethod

public java.lang.Object riInvokeExportedMethod(java.lang.Object target,
                                               java.lang.String methodName,
                                               java.lang.String[] argTypes,
                                               java.lang.Object[] args)

isMarshalledLocally

public boolean isMarshalledLocally()

detach

public void detach()

Specified by:

detach in interface WSApplicationModuleMarshaller

afterActivation

public void afterActivation(int activationMode)

Specified by:

afterActivation in interface WSApplicationModuleMarshaller

isDetached

public boolean isDetached()

getUserRoles

public java.lang.String[] getUserRoles()

Description copied from interface: Session

Returns the Roles/Groups for current user principal.

Specified by:

getUserRoles in interface Session

isUserInRole

public boolean isUserInRole(java.lang.String role)

Specified by:

isUserInRole in interface Session

Parameters:

role - the name of the role.

Returns:

true if the user is in role; false otherwise.

isClient

public boolean isClient()

Description copied from interface: Session

Returns whether this session is running as a client in 3 tier or not.

Specified by:

isClient in interface Session

Returns:

true if the session is in 3 tier. false if in 2 tier.

createInstance

public static ApplicationModuleImpl createInstance(ResponseValues amInfo)
                                            throws ApplicationModuleCreateException

Throws:

ApplicationModuleCreateException

bindToWorkingSet

public void bindToWorkingSet(WSApplicationModuleImpl wsAM)

Specified by:

bindToWorkingSet in interface WSApplicationModuleMarshaller

getCurrentWorkingSet

public WSApplicationModuleImpl getCurrentWorkingSet()

Specified by:

getCurrentWorkingSet in interface WSApplicationModuleMarshaller

getClientProxyInterfaceName

public java.lang.String getClientProxyInterfaceName()

Specified by:

getClientProxyInterfaceName in interface WSApplicationModuleMarshaller

invokeMethod

public java.lang.Object invokeMethod(java.lang.Object target,
                                     java.lang.String methodName,
                                     java.lang.String[] argTypeNames,
                                     java.lang.Object[] args)

Specified by:

invokeMethod in interface WSApplicationModuleMarshaller

syncMarshaller

public void syncMarshaller(ServiceMessage svcMsg)

Specified by:

syncMarshaller in interface WSApplicationModuleMarshaller

getReleaseLevel

public int getReleaseLevel()

Description copied from interface: ApplicationModule

Returns the release level that should be employed by clients of this ApplicationModule.

For example, the ADF/BC DataControl will invoke getReleaseLevel() to determine if this ApplicationModule may be released to the ApplicationPool in SHARED_MANAGED_RELEASE_MODE or if the ApplicationModule may be released in RESERVED_UNMANAGED_RELEASE_MODE.

Two release levels are currently supported:

RELEASE_LEVEL_MANAGED Default. Indicates that the ApplicationModule is in a state that may be managed by BC4J state management service.

For more information about the BC4J state management service please see the passivation documentation.

RELEASE_LEVEL_RESERVED Indicates that the ApplicationModule may not be managed by the BC4J state management service. ApplicationModules may specify this release level if they reference session/txn state that may not be recreated by passivation/activation.

Common examples of state that is not currently managed by the state management service are posted database changes and database locks. Other custom examples may exist.

Care should be taken that the default RELEASE_LEVEL_MANAGED level is used for most releases. Using a RELEASE_LEVEL_RESERVED level throughout an application could result in scalability issues as ApplicationModules accumulate with the accumulation of new sessions.

If both flags have been specified then RELEASE_LEVEL_RESERVED will take precedence.

Specified by:

getReleaseLevel in interface ApplicationModule

Returns:

ApplicationModule.RELEASE_LEVEL_MANAGED or ApplicationModule.RELEASE_LEVEL_RESERVED

setReleaseLevel

public void setReleaseLevel(int releaseLevel)

Specified by:

setReleaseLevel in interface ApplicationModule

See Also:

{@link #getReleaseLevel()}

resetMarshaller

public void resetMarshaller()

Specified by:

resetMarshaller in interface ObjectMarshaller