au.gov.tas.dpiwe.mr
Class Container

java.lang.Object
  au.gov.tas.dpiwe.mr.util.Messenger
      au.gov.tas.dpiwe.mr.BeanCache
          au.gov.tas.dpiwe.mr.PresentationUtilities
              au.gov.tas.dpiwe.mr.BeanBundler
                  au.gov.tas.dpiwe.mr.server.database.QueryBuilder
                      au.gov.tas.dpiwe.mr.Container

All Implemented Interfaces:

Principal, UserTransaction

Direct Known Subclasses:

DaemonContainer

public abstract class Container
extends QueryBuilder
implements UserTransaction, Principal

The Mr Architecture Container is a variant of an EJB container which makes assumptions which allow it to manipulate business objects (or entity beans in EJB nomenclature) without deployment descriptors. Business objects suitable for deployment in this container are referred to as Mr Beans.

The Mr Architecture Container can be thought of as containing business objects (EntityBean implementations), their home interface client implementations (EJBLocalHome implementations), and their local component interface client implementations (EJBLocalObject implementations). Collectively, a business object implementation and its associated component and home interface implementations are called a bean type.

The Container provides an internal interface to allow bean life-cycle events to be initiated and to obtain beans matching particular selection criteria, and also provides an external interface for obtaining beans by querying the relational database storage. It also manages transactions involving beans belonging to it, providing an external interface to allow transactions to be demarcated. While parts of the internal interface are exposed to clients, clients must not use them or rely on their functionality, as their specifications are subject to change without notice. Such methods will be flagged with a comment such as "this method is not intended to be used by external clients."

In keeping with the names of the EJB superinterfaces, and because this container, and therefore the beans it supports, only provides local component views, the convention is to name the component interface for an abstract entity bean classes named <entity-bean-class-name> with the suffix "Object" (even though that class will paradoxically define an interface) viz <entity-bean-class-name>Object, and to name the home interface with the suffix "Home" viz <entity-bean-class-name>Home.

The assumptions made about bean types (beyond the fact that these should comply, except where noted below, with the EJB 2.0 specification's restrictions on beans with container-managed persistence and local home and component interfaces) from the perspective of the bean developer are as follows:

• Each bean type is assumed to have a corresponding table or view in an associated database schema with the same name as the entity bean class.
• Persistent fields in beans have corresponding getter and setter methods with names of the form get<field-name>() and set<field-name>(). The field names in these methods (with the exception of getters and setters for composite fields and composite composite-field components) should be the same as those naming the corresponding columns of the database table or view corresponding to the bean. Persistent field getter and setter methods must be abstract, in accordance with EJB 2.0 CMP, and implementations of them are provided by the DeploymentTool.
• Composite persistent fields, particularly useful in the case of primary and foreign keys, are allowed. These are implemented as ordinary objects, with hashCode() and equals() methods defined, which themselves contain getters and setters on further (possibly composite) persistent fields. The naming convention remains the same as if those getters and setters were declared in the bean itself. The getters and setters for the composite persistent fields should be abstract, implementations provided by DeploymentTool, but the getters and setters in the composite classes must be implemented manually. EJB 2.0 CMP does not support composite persistent fields.
• Primary key fields, and foreign key fields used in abstract getters and setters, (see below) must be modelled consistently as composite persistent fields (see above). This includes where primary key fields are passed parameters to create(), findByPrimaryKey(), ejbCreate() and ejbPostCreate(). It is up to the user whether to use composite or separated forms (or both) as parameters to find[All]WhereFieldsEqual() and find[All]In<field-name>Order() methods. The use of composite persistent fields in beans and their object types in the signatures of create() and ejbCreate(), required in Mr Architecture 2.0, is not allowed in EJB 2.0 CMP.
• Relationship fields in beans have corresponding getter and setter methods with names of the form get<associated-table-name>[s](), which returns a bean object (collection), or set<associated-table-name>[s](), which accepts a bean object (collection) as a parameter. The setter methods should not be exposed in the bean object interface.
  • The association in the case of a getter or setter which manipulates a single bean object has a multiplicity of one (1) to zero or one (0..1), with the name of the primary key field in the (1) bean object determining which field in the associated (0..1) object is used as the foreign key. This situation is most common when the association is one of possibly many aggregations of heterogeneous bean types. Relationship fields of this form may be declared abstract, in accordance with EJB 2.0 CMP, and an implementation will be provided by DeploymentTool.
  • The association in the case of a getter or setter which manipulates a bean object collection has a multiplicity of one (1) to zero or more (0..*), with the name of the primary key field in the (1) bean object determining which field in the associated (0..*) bean objects is used as the foreign key. This situation is most common when the association is an aggregation of homogeneous bean types. Relationship fields of this form may be declared abstract, in accordance with EJB 2.0 CMP, and an implementation will be provided by DeploymentTool.
    • An abstract relate<associated-table-name>() method may accompany a 1 to 0..* relationship if it is UML changeable or addOnly. Such a method is required under Mr Architecture 2.0 as it does not allow direct manipulation of the relationship collection (which is why the setter method is not permitted to be exposed.)
    • Similarly, an abstract unrelate<associated-table-name>() method may be provided for changeable relationships but not for addOnly relationships.
    • The inclusion of relators and unrelators is outside the EJB 2.0 specification. In order for a bean to comply with EJB 2.0, these methods would need to be non-abstract business methods which interact with the respective relationship collection in an appropriate way. A future tool may provide for such a mapping as part of translating Mr Beans into standard EJBs.
  • Other associations may be modelled as business getter and setter methods, or (as an alternative to getters) as business methods starting with the letters "retrieve" (but not "retrieveDynamic"). The advantage of the latter is that such methods are called as part of the loading process of beans returned by a findAll...() method executed with respect to a ClientContainer with a minimal performance hit. A common use of such retriever methods is to ensure that data in lookup tables is retrieved and cached in transient fields in the bean along with persistent field data. Non-abstract getters, retrievers and setters are business methods in accordance with EJB 2.0.
• There was a restriction in versions of Mr Architecture pre-2.0 that an entity bean class may only have two other methods starting with the letters "get" or "set": setEntityContext(), as defined in the EntityBean interface, and getClass(), as defined in the Object superclass. This restriction is lifted as of Mr Architecture 2.0, and non-abstract getters and setters are treated as other business methods. The restriction was contrary to EJB 2.0 CMP.
• Each home interface may define a create() method with the parameter being of the primary key type for the corresponding entity bean. It is also permissible to define a create() method with no parameter provided that a suitable sequence can be extracted for the table in the database corresponding to this home. This sequence should be called "<table-name>_Seq". No other create() methods are allowed, which is contrary to EJB 2.0. This restriction may be lifted in the future.
• Each home interface must define a findByPrimaryKey() method with the parameter being of the primary key type for the corresponding entity bean. A home interface, if it defines findByPrimaryKey(), may also define findAllByPrimaryKey().
• Each home interface may define one or more findWhereFieldsEqual() method whose signatures gives the correct leaf names and types of fields which may exist anywhere within the composite field structure of the corresponding entity bean. Where another bean relies on being able to find objects in this home by a foreign key, this foreign key must be listed in the findWhereFieldsEqual() method with the longest signature. A home interface, if it defines a findWhereFieldsEqual(), may also define a findAllWhereFieldsEqual(). It must define findAllWhereFieldsEqual() if population of a bean collection of this bean type may occur as part of another findAllWhereFieldsEqual() or findAllByPrimaryKey() method in another home. In this case, the signature of the longest findAllWhereFieldsEqual() method must match the signature of the longest findWhereFieldsEqual() method.
• Each home interface may define one or more findIn<field-name>Order() method whose signatures gives the correct leaf names and types of fields which may exist anywhere within the composite field structure of the corresponding entity bean. A home interface, if it defines a findIn<field-name>Order(), may also define a findAllIn<field-name>Order().

Since:

Mr Architecture 1.0

Version:

1.0.5.1

Author:

Kade Hansson

Nested Class Summary

Nested classes/interfaces inherited from class au.gov.tas.dpiwe.mr.BeanCache

BeanCache.ReferenceReaper, BeanCache.TypeRecord

Field Summary

protected String	appName The name of the application to which this container belongs.
protected int	batchFindTimeout The number of seconds before a batch find is in danger of being terminated.
protected Map	batchThreadGroupBadCommandExceptionTable Lists the exception thrown by the last bad command in a batch find.
protected Map	batchThreadGroupBadCommandIndexWaveCountTable Lists the index and wave of the last bad command in a batch find.
protected Map	batchThreadGroupCommandTable Lists the commands for each thread group participating in a batch find.
protected Map	batchThreadGroupResponseTable Lists the responses in the most recent wave for each thread group whose batch find has succeeded.
protected Map	batchThreadGroupWaveCountTable Lists the current wave of commands which have been sent (0 if the first wave has not yet been sent.)
protected Map	batchThreadGroupWaveResponseTable Lists the responses for each wave in each thread group participating in a batch find.
protected Class[]	dateSignature The signature of the setLastUpdateDateTime() methods in entity beans.
protected Method	executeBatchFind The method which executes a batch find.
protected Map	handleCommandTable Lists the commands for each registered non-thread transaction.
protected Method	initiateBatchFind The method which initiates a batch find.
protected Class[]	integerSignature The signature of the getter methods in the ResultSet that we use.
protected static Container	localContainer A reference to the local container if an unnamed application has instatiated a container in this VM.
protected static Map	localContainers A table listing the local containers on a per application basis.
protected Class	setClass The ResultSet class which returns the result of SQL queries.
protected Method	setWasNull The ResultSet.wasNull() method.
protected Class[]	stringSignature The signature of the setLastUpdateUsername() methods in entity beans.
protected PerThread	threadBadCommandIndex The index to the command that failed in the most recent doCommands() call.
protected PerThread	threadBatchFind The batch find corresponding to this thread.
protected PerThread	threadCommands The non-committed commands corresponding to this thread.
protected Map	threadGroupBatchFindTable Lists the thread groups participating in batch finds.
protected Map	transactionThreadNameCommandTable Lists the commands for each registered transaction thread.
protected Set	transactionThreadRollbackOnlyList Lists the transaction threads or handles which are marked as rollback only.
protected int	transactionTimeout The number of seconds before a transaction is in danger of being terminated.
protected Class	userEntityBeanClass The class involved in user authentication.

Fields inherited from class au.gov.tas.dpiwe.mr.server.database.QueryBuilder

database

Fields inherited from class au.gov.tas.dpiwe.mr.PresentationUtilities

annotationSignature, beanFieldNameCollectionGetterMethodTable, beanFieldNameConstructorMethodTable, beanFieldNameDestructorMethodTable, beanFieldNameGetterMethodTable, beanFieldNamePostRelatorMethodTable, beanFieldNameRelatorMethodTable, beanFieldNameSetterMethodTable, beanFieldNameTable, beanPrefixTable, CSVDateTime_MillisecondAsFractionOfDay, Format_None, Format_UnicodeTF16CSV, Format_UnicodeTF16Quoted, Format_UnicodeTF16WithUnits, Format_UnicodeTF16XML, Format_UnicodeTF8CSV, Format_UnicodeTF8Quoted, Format_UnicodeTF8URLEncoded, Format_UnicodeTF8WithUnits, Format_UnicodeTF8XML, XMLDateTime_DateFormatter, XMLDateTime_DateLength, XMLDateTime_DateTimeFormatter, XMLDateTime_DateTimeLength, XMLDateTime_RFC822ZoneFormatter, XMLDateTime_TimeFormatter, XMLDateTime_TimeLength, XMLDateTime_TimezoneLength

Fields inherited from class au.gov.tas.dpiwe.mr.BeanCache

addingLegacy, beanCache, beanClassMethodTable, beanClassTable, beanHistogram, clientCachedBeanLifetime, componentClassMethodTable, deferredCacheableList, deferredHistoricCommandList, deferredKeyGetterMethodNameTable, deferredKeySetterMethodNameTable, deferredKeyTypeNameTable, deferredTrailList, deferredUnderscoreList, historicCommandPoolTable, homeInterfaceMethodTable, homeInterfaceTable, initialPerBeanClassCacheSize, keyClassTable, keyGetterTable, keySetterTable, lastPurgeEndSequenceNo, objectCache, objectClassMethodTable, objectClassTable, objectHistogram, objectInterfaceList, reaper, removedBeans, removedObjects, tableNameLCToTableNameMapping, tableNameToBeanClassMapping, totalBeans, totalObjects, trailList, underscoreList

Fields inherited from class au.gov.tas.dpiwe.mr.util.Messenger

console, error, exceptionMessageTable, exceptionsToConsole, exceptionsToError, Level_Debug, Level_Exception, Level_None, Level_Normal, messageLevel

Constructor Summary

protected	Container(int beanClassCount, int initialPerBeanClassCacheSize, String appName) This class is abstract and cannot be instantiated.
protected	Container(String appName) This class is abstract and cannot be instantiated.

Method Summary

EntityBean	activateEntityBean(EntityBean bean) The immediate action of this method is to reactivate a bean after transmission across a communication link or storage in a file.
EntityBean	activateEntityBean(EntityBean bean, boolean recurse) The immediate action of this method is to reactivate a bean after transmission across a communication link or storage in a file.
EntityBean	activateEntityBean(MrEntityBean bean, boolean recurse, boolean cache) The immediate action of this method is to reactivate a bean after transmission across a communication link or storage in a file.
protected void	activateEntityBeanRelatives(EntityBean bean, boolean cache) Internal utility method to activate entity beans related to this entity bean.
void	addType(Class beanClass, Method keyGetterMethod, Method keySetterMethod, Class homeClass, Class objectClass) Adds a recognised bean type to this container.
void	addTypeLater(String abstractBeanClassQualifiedName, String keyTypeQualifiedName, String keyFieldName) Queues a recognised bean type to be added to this container at its first use.
AlertResponse	alertServer(int oldAlertStatus, int newAlertStatus)
boolean	areBeanObjectRelativesPersistent(BeanWrapper beanObject, boolean relativesPersistent) Internal utility method to determine if the direct and indirect relationships of a bean object are persistent.
protected Batch	batchRetrieveMethodCallsForBeanObject(Batch batch, BeanWrapper beanObject) Internal utility method to batch calls to the methods starting with the word "retrieve" in a particular bean object.
protected Batch	batchRetrieveMethodCallsForBeanObjects(Batch batch, Collection beanObjects) Internal utility method to batch calls to the methods starting with the word "retrieve" in a collection of bean objects.
void	begin() Creates a new transaction and associates it with the current thread.
void	begin(int size) Creates a new transaction and associates it with the current thread.
protected Collection	begin(Object handle, int size) Creates a new transaction and associates it with the given object.
void	bind(Object handle) Bind a thread to the given transaction (assuming it exists.)
void	commit() Complete the transaction being managed for the calling thread.
protected void	commit(Object handle) Complete the given transaction.
EJBLocalObject	convertPrototypeFromDefaultDatabaseWildcards(EJBLocalObject beanObject) Takes a prototype bean, and transforms String fields containing the default database wildcards into Strings containing the wildcards appropriate for the MrDatabase instance associated with this Container.
EJBLocalObject	convertPrototypeToDefaultDatabaseWildcards(EJBLocalObject beanObject) Takes a prototype bean, and transforms String fields containing the database wildcards appropriate for the MrDatabase instance associated with this Container into Strings containing the default wildcards.
void	copyUpdateStampFromEntityBeanToBean(EntityBean sourceBean, EntityBean objectBean) Internal utility method sets the last update date/time and username field values for one entity bean to those of another.
EntityBean	createEntityBean(EntityBean bean, Object primaryKey) The immediate action of this method is to create a single entity bean with the specified primary key.
EntityBean	createEntityBeanImmediately(EntityBean bean, Object primaryKey) The immediate action of this method is to create a single entity bean with the specified primary key.
void	debugTransaction() Prints (if debugging is enabled) the contents of the current transaction for this thread.
Response	doCommand(Command command) Internal method to perform a single command immediately.
abstract Response	doCommand(Command command, boolean oneOff) Internal method to perform a single command immediately.
protected Response	doCommandInTransactionContext(Command command) Internal method which executes a command (a) immediately if the calling thread has no defined transaction context or (b) at commit time if the calling thread is presently in the context of a transaction.
abstract Collection	doCommands(Collection commands) Internal method to perform a batch of commands.
boolean	equals(Object another) Does a crude test to check if two Containers contain the same types.
void	executeBatchFind() Executes a batch find operation.
void	executeRetrieveMethodCallsForBeanObject(BeanWrapper beanObject) Internal utility method to invoke methods starting with the word "retrieve" in a particular bean object.
Collection	executeRetrieveMethodCallsForBeanObjects(Collection beanObjects) Internal utility method to invoke methods starting with the word "retrieve" in a collection of bean objects.
Map	executeRetrieveMethodCallsForBeanObjects(Map beanObjects) Internal utility method to invoke methods starting with the word "retrieve" in a map of bean objects.
EntityBean	findAllOfEntityBean(EntityBean bean, Object primaryKey) The immediate action of this method is to load a single entity bean from persistent storage.
EntityBean	findEntityBean(EntityBean bean, Object primaryKey) The immediate action of this method is to load a single entity bean from persistent storage.
static Container	findLocalContainer(String appName) Returns the local container corresponding to the specified application name.
FlushResponse	flushBeans(EntityBean bean) Ensures that beans of the specified type are removed from all caches.
String	getAppName() Returns the application name for this container.
int	getBadCommandIndex(boolean remove) Gives the index of the last command that failed during a doCommands() call for the current thread.
String	getIDForEntityBean(EntityBean bean) This internal utility method returns an identifier for a bean based on its type and primary key.
protected NullableDate	getLastUpdateDateFromEntityBean(EntityBean bean) This internal utility method returns the last update date/time field value for an entity bean.
MrDatabase	getMrDatabase() Get the database object associated with this container, if any.
String	getName() Returns a dummy principal name for this container.
String	getObjectIDForEntityBean(EntityBean bean) This internal utility method returns an identifier for a bean based on its type and primary key.
UserEntityBean	getPooledUserEntityBean() Requests a pooled user entity bean.
boolean	getRollbackOnly() Returns true if the current transaction being managed for the calling thread will never be committed.
boolean	getRollbackOnly(Object handle) Returns true if the specified transaction will never be committed.
Date	getServerDate() The immediate action of this method is to access the server's real-time clock.
Date	getServerDate(TimeZone suggestedTimeZone) The immediate action of this method is to access the server's real-time clock.
int	getStatus() Obtain the status of the transaction associated with the calling thread.
protected int	getStatus(Object handle) Obtain the status of the specified transaction.
Class	getUserEntityBeanClass() Returns a bean type which implements the UserEntityBean interface.
UserTransaction	getUserTransaction(Object handle) Obtain a transaction context which can be shared or automatically suspended/resumed by multiple threads.
int	hashCode() Returns a hashcode for this container.
HeimlichedObstruction	heimlichServer(String serverDumpFilename) Kills all running threads on the server, leaving it in an undefined state.
void	initiateBatchFind(Batch batch) Initiates a batch find operation and associates it with the current thread.
InvokeResponse	invokeMethodOfBeanObject(Method method, EntityBean bean, Object[] parameters) The immediate action of this method is to execute a method of an entity bean on the server.
InvokeResponse	invokeMethodOfHome(Method method, EntityBean bean, Object[] parameters) The immediate action of this method is to execute a method of a home interface on the server.
protected boolean	isCommandWhichExpectsNonPooledBean(Command command) Internal utility method to determine if this command takes a non-pooled bean (i.e. a bean with identity) as an argument.
EntityBean	loadEntityBean(EntityBean bean) The immediate action of this method is to refresh an entity bean from persistent storage.
LockResponse	lockHome(EntityBean bean) The eventual action of this method is to lock the table associated with a particular home until the transaction has completed.
LogResponse	logOnServer(String logMessage) The eventual action of this method is to place a log message in the server log file.
EntityBean	nullifyRelationships(EntityBean bean) This internal utility method sets the relationships of a "Thin" entity bean to null.
EntityBean	passivateEntityBean(EntityBean bean) The immediate action of this method is to passivate a bean ready for transmission across a communication link or storage in a file.
EntityBean	passivateEntityBean(EntityBean bean, boolean recurse) The immediate action of this method is to passivate a bean ready for transmission across a communication link or storage in a file.
protected void	passivateEntityBeanRelatives(EntityBean bean) Internal utility method to passivate entity beans related to this entity bean.
protected void	purgeTimedOutTransactions() Internal method to discard records of aging transactions being managed by the container.
EntityBean	removeEntityBean(EntityBean bean, boolean cloned) The eventual action of this method is to delete an entity bean from persistent storage.
void	removeNonRelatives(Collection beanObjects) Internal utility method to activate the removeUnrelated() and remove() methods of a list of bean objects which are to be unrelated from another bean object.
void	removeNonRelativesFromBeanObjectNonRelatives(Collection beanObjects) Internal utility method to activate the removeUnrelatedFromRelated() and removeUnrelated() methods of a list of bean objects which are to be unrelated from another bean object.
void	removeNonRelativesFromBeanObjectRelatives(BeanWrapper beanObject) Internal utility method to activate the removeUnrelated() methods of all bean objects related to this bean object.
StatusResponse	reportServerStatus()
Map	restoreNonRelativesToBeanObjectRelatives(Collection beanObjects) Internal utility method to activate the restoreUnrelated() and restoreUnrelatedToRelated() methods of a list of bean objects which are to be rerelated to another bean object.
void	rollback() Roll back the transaction associated with the calling thread.
protected void	rollback(Object handle) Roll back the given transaction.
Collection	selectAllOfEntityBeans(EntityBean bean, Collection constrainedFields) The immediate action of this method is to load many entity beans from persistent storage.
Collection	selectAllOfEntityBeansInOrder(EntityBean bean, Collection constrainedFields, String orderFieldName) The immediate action of this method is to load many entity beans from persistent storage.
Collection	selectEntityBeans(EntityBean bean, Collection constrainedFields) The immediate action of this method is to load many entity beans from persistent storage.
Collection	selectEntityBeansInOrder(EntityBean bean, Collection constrainedFields, String orderFieldName) The immediate action of this method is to load many entity beans from persistent storage.
Collection	selectSiameseBeanObjects(String sqlQuery) The immediate action of this method is to load many entity beans from persistent storage.
void	setRollbackOnly() Ensures that the current transaction being managed for the calling thread can never be committed.
protected void	setRollbackOnly(Object handle) Ensures that the specified transaction can never be committed.
void	setTransactionTimeout(int seconds) Determines the age (in seconds) which transactions must reach before they can be discarded.
void	setUserEntityBeanClass(Class beanClass) Specify a bean type which implements the UserEntityBean interface.
void	storeBeanObjectRelatives(BeanWrapper beanObject) Internal utility method to activate the store() methods of all bean objects related to this bean object.
EntityBean	storeEntityBean(EntityBean bean, boolean cloned) The eventual action of this method is to update an entity bean in persistent storage.
String	toString() Returns a string representation of this container.
void	unbind() Unbinds a thread from its transaction (assuming it is bound.)
void	unrelateGivenRelativesFromBeanObjectRelatives(Collection relatives, Map keyEntryTable) Internal utility method to activate the unrelateAllInFlatMap() and unrelateAllInNestedMapFromRelated() methods of a map of bean objects which are to be re-unrelated from the given relatives.
WipeResponse	wipeEntityBeans(EntityBean bean, Collection constrainedFields) The eventual action of this method is to delete many entity beans from persistent storage.

Methods inherited from class au.gov.tas.dpiwe.mr.server.database.QueryBuilder

buildFieldAndValueListForEntityBean, buildQualifiedFieldAndValueListForEntityBean, getCompoundConstraint, getFieldListForCompositeField, getOrderFieldsList, getPrimaryKeyConstraint, getPrimaryKeyConstraint, getPrimaryKeyFieldNames, getTableNameForEntityBean, getTableNameForEntityBeanClass, isDatabaseSpecificFieldType, listFieldTypeConstraintsForTable, listFieldValuesForEntityBean, listOrphanedFields, listQualifiedFieldsForEntityBeans, listUpdateFieldsAndValuesForEntityBean, processJoinedQuery, translateName, translateNames

Methods inherited from class au.gov.tas.dpiwe.mr.BeanBundler

bundleBeanObjectCollectionIntoBeanObjectMap, bundleEntityBeanCollectionIntoEntityBeanList, bundleEntityBeanCollectionIntoEntityBeanMap, bundleEntityBeanCollectionIntoEntityBeanSet, bundleEntityBeanCollectionIntoEntityBeanSortedSet, bundleEntityBeanCollectionIntoPrimaryKeySet, bundleEntityBeanIntoBeanObjectCollection, bundleEntityBeanIntoBeanObjectCollection, bundleEntityBeanIntoBeanObjectList, bundleEntityBeanIntoBeanObjectList, bundleEntityBeanIntoBeanObjectMap, bundleEntityBeanIntoBeanObjectMap, bundleEntityBeanIntoBeanObjectSet, bundleEntityBeanIntoBeanObjectSet, bundleEntityBeanIntoBeanObjectSortedSet, bundleEntityBeanIntoBeanObjectSortedSet, bundleEntityBeanListIntoPrimaryKeySet, bundleEntityBeanMapIntoPrimaryKeySet, bundleEntityBeanSetIntoPrimaryKeySet, bundleEntityBeanSortedSetIntoPrimaryKeySet, bundleThinSiameseBeanIntoSiameseBeanObjectCollection, filterBeanObjectCollection, filterBeanObjectList, filterBeanObjectMap, filterBeanObjectSet, filterBeanObjectSet, unbundleBeanObjectIntoEntityBeanCollection, unbundleBeanObjectIntoEntityBeanList, unbundleBeanObjectIntoEntityBeanMap, unbundleBeanObjectIntoEntityBeanSet, unbundleBeanObjectIntoEntityBeanSet

Methods inherited from class au.gov.tas.dpiwe.mr.PresentationUtilities

buildFieldList, buildFieldListForEntityBean, buildFieldNameGetterMethodTable, buildFieldNameGetterMethodTable, buildFieldNameSetterMethodTable, buildFieldNameSetterMethodTable, buildFieldNameValueTable, buildFieldNameValueTable, decodeAlgebraic, decodeAlgebraic, decodeAlgebraic, decodeAlgebraic, decodeAlgebraic, decodeAlgebraic, decodeAlgebraic, decodeAlgebraic, decodeAlgebraic, decodeAlgebraic, decodeAlgebraic, decodeBasicValue, decodeBasicValues, decodeSpecialValue, expressBasicValue, expressBasicValues, expressSpecialValue, expressVCD, getDestructorsForField, getFieldTypeByName, getFieldValueByName, getParentObjectForField, getPrototypeBeanObjectForBeanType, getPrototypeBeanObjectForTableName, getPrototypeFieldValueByName, getReadableFieldNamesInCSVFormat, getReadableFieldNamesInQueryOrder, getReadableFieldsAsMap, getReadableFieldsInURLEncodedFormat, getReadableFieldsInXMLFormat, getReadableFieldValuesInCSVFormat, getReadableFieldValuesInQueryOrder, isBasicFieldType, isCollectionType, isFieldPartOfCompositePrimaryKey, isRangeType, isRelationshipField, isRelationshipField, isRelationshipField, isSpecialCollectionType, isSpecialFieldType, isYesOrNoField, isYesOrNoField, leapYearsSince1900, listFieldsForEntityBean, main, newVCD, nonLeapYearsSince1900, replaceCompositePrimaryKeyWithClone, setFieldValueByName, setWriteableFieldsGivenCSVLine, setWriteableFieldsGivenMap, setWriteableFieldsGivenXMLFragment, stripPrefixFromFieldName, validateEntityBean

Methods inherited from class au.gov.tas.dpiwe.mr.BeanCache

addHistoricCommandType, addType, addType, addTypeLater, addTypeLater, beginLegacyTypes, buildFullMethodList, buildMethodList, buildMethodList, buildSinglyInheritedMethodList, cacheBeanObject, cacheEntityBean, classForName, compareEntityBeans, compareEntityBeanTypes, endLegacyTypes, ensureType, ensureTypeIgnoreCase, getAbstractNameForEntityBean, getAbstractNameForEntityBeanClass, getAbstractNameForUIBean, getAbstractNameForUIBeanClass, getAllTypes, getBeanObjectForEntityBean, getBeanObjectForEntityBean, getCachedEntityBean, getHomeForBeanObject, getHomeForEntityBean, getKeyGetterForEntityBean, getKeySetterForEntityBean, getPackageNameForEntityBeanClass, getPooledBeanObjectForEntityBean, getPooledBeanObjectForEntityBean, getPooledEntityBean, getPooledEntityBean, getPooledEntityBean, getPrimaryKeyFieldNameForEntityBean, getPrimaryKeyFieldNameForEntityBeanClass, getPrimaryKeyFieldTypeNameForEntityBeanClass, getType, getTypeIgnoreCase, hashEntityBean, hashEntityBeanType, isCachedEntityBean, loadTypeForName, loadTypeOnNull, loadTypes, loadTypes, logCacheHistogram, logCacheStats, reapReferences, shutdown, throwOnNull, throwOnNull, uncacheBeanObjectForEntityBean, uncacheBeans, uncacheEntityBean

Methods inherited from class au.gov.tas.dpiwe.mr.util.Messenger

debugEmptyMessage, debugEmptyMessage, debugMessage, debugMessage, debugMessage, debugMessageFirstPart, debugMessageFirstPart, debugMessageLastPart, debugMessageLastPart, debugMessagePart, debugMessagePart, debugStackTrace, debugStackTrace2, emptyMessage, emptyMessage, emptyMessage, emptyMessage, getMessageLevel, isTweenMessage, message, message, message, message, message, message, messageFirstPart, messageFirstPart, messageFirstPart, messageFirstPart, messageLastPart, messageLastPart, messageLastPart, messageLastPart, messagePart, messagePart, messagePart, messagePart, messagePart, messagePart, prettyException, queryReport, setConsoleOutput, setConsoleOutput, setErrorOutput, setErrorOutput, setMessageLevel, setOutput, stackTrace, stackTrace2, success, success

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

transactionThreadNameCommandTable

protected Map transactionThreadNameCommandTable

Lists the commands for each registered transaction thread. Also, this is the object whose lock is used as the semaphore for batch finds.

transactionThreadRollbackOnlyList

protected Set transactionThreadRollbackOnlyList

Lists the transaction threads or handles which are marked as rollback only.

threadCommands

protected PerThread threadCommands

The non-committed commands corresponding to this thread.

handleCommandTable

protected Map handleCommandTable

Lists the commands for each registered non-thread transaction.

threadBatchFind

protected PerThread threadBatchFind

The batch find corresponding to this thread.

threadBadCommandIndex

protected PerThread threadBadCommandIndex

The index to the command that failed in the most recent doCommands() call.

batchThreadGroupWaveCountTable

protected Map batchThreadGroupWaveCountTable

Lists the current wave of commands which have been sent (0 if the first wave has not yet been sent.)

batchThreadGroupCommandTable

protected Map batchThreadGroupCommandTable

Lists the commands for each thread group participating in a batch find.

batchThreadGroupWaveResponseTable

protected Map batchThreadGroupWaveResponseTable

Lists the responses for each wave in each thread group participating in a batch find.

batchThreadGroupBadCommandIndexWaveCountTable

protected Map batchThreadGroupBadCommandIndexWaveCountTable

Lists the index and wave of the last bad command in a batch find.

batchThreadGroupBadCommandExceptionTable

protected Map batchThreadGroupBadCommandExceptionTable

Lists the exception thrown by the last bad command in a batch find.

threadGroupBatchFindTable

protected Map threadGroupBatchFindTable

Lists the thread groups participating in batch finds.

batchThreadGroupResponseTable

protected Map batchThreadGroupResponseTable

Lists the responses in the most recent wave for each thread group whose batch find has succeeded.

userEntityBeanClass

protected Class userEntityBeanClass

The class involved in user authentication.

transactionTimeout

protected int transactionTimeout

The number of seconds before a transaction is in danger of being terminated.

batchFindTimeout

protected int batchFindTimeout

The number of seconds before a batch find is in danger of being terminated.

setClass

protected Class setClass

The ResultSet class which returns the result of SQL queries.

integerSignature

protected Class[] integerSignature

The signature of the getter methods in the ResultSet that we use.

setWasNull

protected Method setWasNull

The ResultSet.wasNull() method.

initiateBatchFind

protected Method initiateBatchFind

The method which initiates a batch find.

executeBatchFind

protected Method executeBatchFind

The method which executes a batch find.

dateSignature

protected Class[] dateSignature

The signature of the setLastUpdateDateTime() methods in entity beans.

stringSignature

protected Class[] stringSignature

The signature of the setLastUpdateUsername() methods in entity beans.

localContainer

protected static Container localContainer

A reference to the local container if an unnamed application has instatiated a container in this VM.

localContainers

protected static Map localContainers

A table listing the local containers on a per application basis.

appName

protected String appName

The name of the application to which this container belongs.

Constructor Detail

Container

protected Container(String appName)

This class is abstract and cannot be instantiated.

This constructor is called by subclasses to initialize the hashtables and hash sets which are common to all implementations.

It chooses default hashtable sizes based on a medium-sized business application with a couple of hundred bean types.

Parameters:

appName - the name of the application which requires this container, usually the qualified name of the main application package, with an additional suffix if there are multiple containers per application.

Container

protected Container(int beanClassCount,
                    int initialPerBeanClassCacheSize,
                    String appName)

This class is abstract and cannot be instantiated.

This constructor is called by subclasses to initialize the hashtables and hash sets which are common to all implementations.

Parameters:

beanClassCount - an estimate of the number of bean types this container will contain.

initialPerBeanClassCacheSize - an estimate of the number of beans that will exist in the cache for a particular bean type.

appName - the name of the application which requires this container, usually the qualified name of the main application package, with an additional suffix if there are multiple containers per application.

Method Detail

findLocalContainer

public static Container findLocalContainer(String appName)

Returns the local container corresponding to the specified application name.

Parameters:

appName - the name of the application whose container is required, further qualified if there are multiple containers for that application, or null if only one application is running in this VM.

Returns:

the local container for the specified application name, or null if no container has yet been instatiated.

getAppName

public String getAppName()

Returns the application name for this container.

Returns:

the name of the application to which this container belongs, further qualified if there are multiple containers for the application, or null if only one application is running in this VM.

addTypeLater

public void addTypeLater(String abstractBeanClassQualifiedName,
                         String keyTypeQualifiedName,
                         String keyFieldName)
                  throws InvocationTargetException,
                         IllegalAccessException,
                         NoSuchMethodException,
                         InstantiationException

Queues a recognised bean type to be added to this container at its first use.

This method is called by external clients to inform the container of each bean type it needs to recognise.

Parameters:

abstractBeanClassQualifiedName - the fully qualified name of the abstract bean class.

keyTypeQualifiedName - the fully qualified name of the primary key type.

keyGetterMethodName - the name of the primary key getter method in the abstract bean.

keySetterMethodName - the name of the primary key setter method in the abstract bean.

Throws:

InvocationTargetException

IllegalAccessException

NoSuchMethodException

InstantiationException

addType

public void addType(Class beanClass,
                    Method keyGetterMethod,
                    Method keySetterMethod,
                    Class homeClass,
                    Class objectClass)
             throws InvocationTargetException,
                    IllegalAccessException,
                    NoSuchMethodException,
                    InstantiationException

Adds a recognised bean type to this container.

This method is called by external clients to inform the container of each bean type it needs to recognise.

Parameters:

beanClass - the "Thin" entity bean implementation which identifies this type, as generated by DeploymentContainer.

keyGetterMethod - the primary key getter method in the "Thin" entity bean.

keySetterMethod - the primary key setter method in the "Thin" entity bean.

homeClass - the EJBLocalHome implementation for this entity bean type, as generated by DeploymentContainer.

objectClass - the EJBLocalObject implementation for this entity bean type, as generated by DeploymentContainer.

Throws:

NoSuchMethodException - if the home interface implementation doesn't have a constructor of the appropriate form.

IllegalAccessException - if the home interface implementation doesn't have a public constructor of the appropriate form.

InstantiationException - if the home interface implementation could not be instantiated because it is an interface or abstract.

InvocationTargetException - if the home interface implementation constructor throws an exception.

getMrDatabase

public MrDatabase getMrDatabase()

Get the database object associated with this container, if any.

If this container is only indirectly connected to a database, this call returns a generic database object which cannot be used to obtain connections to any database.

Parameters:

bean - a "Thin" entity bean prototype.

Returns:

the MrDatabase this container is directly or indirectly using, or null if this container does not use a database in its implementation.

setUserEntityBeanClass

public void setUserEntityBeanClass(Class beanClass)
                            throws EJBException

Specify a bean type which implements the UserEntityBean interface. This bean type is used by the command servlet to perform authentication.

Parameters:

beanClass - the "Thin" entity bean class which implements the UserEntityBean interface.

Throws:

EJBException

See Also:

UserEntityBean

getUserEntityBeanClass

public Class getUserEntityBeanClass()
                             throws EJBException

Returns a bean type which implements the UserEntityBean interface. This bean type is used by the command servlet to perform authentication.

Returns:

the "Thin" entity bean class which implements the UserEntityBean interface, or null if this server does not authenticate.

Throws:

EJBException

See Also:

UserEntityBean

getPooledUserEntityBean

public UserEntityBean getPooledUserEntityBean()
                                       throws EJBException

Requests a pooled user entity bean.

Parameters:

bean - a user entity bean prototype.

Returns:

a pooled user entity bean.

Throws:

EJBException - if the user entity bean doesn't have a constructor of the appropriate form, if the user entity bean doesn't have a public constructor of the appropriate form, if the user entity bean could not be instantiated because it is an interface or abstract, or if the user entity bean constructor throws an exception.

getLastUpdateDateFromEntityBean

protected NullableDate getLastUpdateDateFromEntityBean(EntityBean bean)

This internal utility method returns the last update date/time field value for an entity bean.

Parameters:

bean - the entity bean to return the update date/time for.

Returns:

the last update date/time field value for the entity bean, or a null representation if the field is null or doesn't exist.

getServerDate

public Date getServerDate()
                   throws EJBException

The immediate action of this method is to access the server's real-time clock.

Returns:

the server date and time.

Throws:

EJBException - the action failed.

getServerDate

public Date getServerDate(TimeZone suggestedTimeZone)
                   throws EJBException

The immediate action of this method is to access the server's real-time clock.

This method may only be called remotely if the user is logged in with administrator privileges. As with all security constraints, this is enforced by the servlet security tier.

Parameters:

suggestedTimeZone - the timezone which it is suggested that the server should be operating in.

Returns:

the server date and time.

Throws:

EJBException - the action failed.

getUserTransaction

public UserTransaction getUserTransaction(Object handle)

Obtain a transaction context which can be shared or automatically suspended/resumed by multiple threads.

Parameters:

handle - the object designated as the owner of the context.

Returns:

the transaction context.

bind

public void bind(Object handle)

Bind a thread to the given transaction (assuming it exists.)

This is a low-level call, and should be used with caution. Calling it for threads which are already bound to a transaction but weren't themselves bound using a call to bind() could produce unpredictable behaviour.

Parameters:

handle - the owner of the transaction to bind to.

unbind

public void unbind()

Unbinds a thread from its transaction (assuming it is bound.)

This is a low-level call, and should be used with caution. Calling it for threads which weren't bound using a call to bind() could produce unpredictable behaviour.

setTransactionTimeout

public void setTransactionTimeout(int seconds)

Determines the age (in seconds) which transactions must reach before they can be discarded.

May be called by bean providers and external clients. Be aware that this change will be system wide.

Specified by:

setTransactionTimeout in interface UserTransaction

Parameters:

seconds - timeout in seconds.

begin

public void begin()
           throws NotSupportedException

Creates a new transaction and associates it with the current thread.

May be called by bean providers in business methods and by external clients. Bean providers should call this method via the UserTransaction object provided in response to EntityContext.getUserTransaction() to ensure that the bean is not specific to this architecture.

Specified by:

begin in interface UserTransaction

Throws:

NotSupportedException - if an attempt is made to nest transactions.

begin

public void begin(int size)
           throws NotSupportedException

Creates a new transaction and associates it with the current thread.

May be called by bean providers in business methods and by external clients. Bean providers should call this method via the UserTransaction object provided in response to EntityContext.getUserTransaction() to ensure that the bean is not specific to this architecture.

Parameters:

size - the expected number of commands in this transaction.

Throws:

NotSupportedException - if an attempt is made to nest transactions.

begin

protected Collection begin(Object handle,
                           int size)
                    throws NotSupportedException

Creates a new transaction and associates it with the given object.

Parameters:

handle - the object to manage a thread on behalf of.

size - the expected number of commands in this transaction.

Returns:

the collection of commands for this transaction.

Throws:

NotSupportedException - if an attempt is made to nest transactions.

initiateBatchFind

public void initiateBatchFind(Batch batch)

Initiates a batch find operation and associates it with the current thread.

Parameters:

batch - the batch of jobs participating in this batch find.

purgeTimedOutTransactions

protected void purgeTimedOutTransactions()

Internal method to discard records of aging transactions being managed by the container.

findEntityBean

public EntityBean findEntityBean(EntityBean bean,
                                 Object primaryKey)
                          throws EJBException

The immediate action of this method is to load a single entity bean from persistent storage. The loading occurs immediately, even if a transaction is being managed for the calling thread. The data retrieved will not reflect changes stored but not yet committed.

Any relationships to other beans are populated with null values. The effect of this is that the bean objects created from the entity beans returned from this method will defer loading of any beans they are related to until these relationships are explored. This method therefore is faster and more space efficient than selectAllOfEntityBeans(), but for each subsequent traversal of a relationship in the resulting bean objects there will be a performance hit.

This method should not be called by external clients. Call findByPrimaryKey() on the home interface instead.

This method is called by the implementation of an entity bean's home interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - an entity bean prototype for the bean which will be found in persistent storage.

primaryKey - determines the entity bean found.

Returns:

the entity bean found.

Throws:

EJBException - the action failed.

findAllOfEntityBean

public EntityBean findAllOfEntityBean(EntityBean bean,
                                      Object primaryKey)
                               throws EJBException

The immediate action of this method is to load a single entity bean from persistent storage. The loading occurs immediately, even if a transaction is being managed for the calling thread. The data retrieved will not reflect changes stored but not yet committed.

The bean loaded will immediately load all the beans it is related to. This method therefore carries a higher time and space overhead than findEntityBean(), but may offer a performance benefit in the long run if all the relationships are likely to be used subsequently.

This method should not be called by external clients. Call findAllByPrimaryKey() on the home interface instead.

This method is called by the implementation of an entity bean's home interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - an entity bean prototype for the bean which will be found in persistent storage.

primaryKey - determines the entity bean found.

Returns:

the entity bean found.

Throws:

EJBException - the action failed.

createEntityBean

public EntityBean createEntityBean(EntityBean bean,
                                   Object primaryKey)
                            throws EJBException,
                                   CreateException

The immediate action of this method is to create a single entity bean with the specified primary key. Persistant storage is checked to make sure that this primary key is not already in use. This is no guarantee that the bean will not exist in the future, created by another client- such conflicts will be resolved at the time of commission of a subsequent store operation.

This method should not be called by external clients. Call create() on the home interface instead.

This method is called by the implementation of an entity bean's home interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - an entity bean prototype for the bean which will be created in persistent storage.

primaryKey - determines the identity of the entity bean created.

Returns:

the new entity bean.

Throws:

EJBException - the action failed.

CreateException - the primary key is already in use.

createEntityBeanImmediately

public EntityBean createEntityBeanImmediately(EntityBean bean,
                                              Object primaryKey)
                                       throws EJBException,
                                              CreateException

The immediate action of this method is to create a single entity bean with the specified primary key. Persistant storage is not checked to make sure that this primary key is not already in use. Conflicts will be resolved at the time of commission of a subsequent store operation.

This method should not be called by external clients. Call createImmediately() on the home interface instead.

This method is called by the implementation of an entity bean's home interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - an entity bean prototype for the bean which will be created in persistent storage.

primaryKey - determines the identity of the entity bean created.

Throws:

EJBException - the action failed.

CreateException - never.

selectEntityBeans

public Collection selectEntityBeans(EntityBean bean,
                                    Collection constrainedFields)
                             throws EJBException

The immediate action of this method is to load many entity beans from persistent storage. The loading occurs immediately, even if a transaction is being managed for the calling thread. The data retrieved will not reflect changes stored but not yet committed.

Any relationships to other beans are populated with null values. The effect of this is that the bean objects created from the entity beans returned from this method will defer loading of any beans they are related to until these relationships are explored. This method therefore is faster and more space efficient than selectAllOfEntityBeans(), but for each subsequent traversal of a relationship in the resulting bean objects there will be a performance hit.

This method should not be called by external clients. Call findWhereFieldsEqual() on the home interface instead.

This method is called by the implementation of an entity bean's home interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - an entity bean prototype for those beans which will be selected from persistent storage.

constrainedFields - determines how the selection is made.

Returns:

the entity beans selected.

Throws:

EJBException - the action failed unexpectedly.

selectAllOfEntityBeans

public Collection selectAllOfEntityBeans(EntityBean bean,
                                         Collection constrainedFields)
                                  throws EJBException

The immediate action of this method is to load many entity beans from persistent storage. The loading occurs immediately, even if a transaction is being managed for the calling thread. The data retrieved will not reflect changes stored but not yet committed.

The beans loaded will immediately load all the beans they are related to. This method therefore carries a higher time and space overhead than selectEntityBeans(), but may offer a performance benefit in the long run if all these relationships are likely to be used subsequently.

This method should not be called by external clients. Call findAllWhereFieldsEqual() on the home interface instead.

This method is called by the implementation of an entity bean's home interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - an entity bean prototype for those beans which will be selected from persistent storage.

constrainedFields - determines how the beans will be selected.

Returns:

the entity beans selected.

Throws:

EJBException - the action failed unexpectedly.

selectEntityBeansInOrder

public Collection selectEntityBeansInOrder(EntityBean bean,
                                           Collection constrainedFields,
                                           String orderFieldName)
                                    throws EJBException

The immediate action of this method is to load many entity beans from persistent storage. The loading occurs immediately, even if a transaction is being managed for the calling thread. The data retrieved will not reflect changes stored but not yet committed.

Any relationships to other beans are populated with null values. The effect of this is that the bean objects created from the entity beans returned from this method will defer loading of any beans they are related to until these relationships are explored. This method therefore is faster and more space efficient than selectAllOfEntityBeans(), but for each subsequent traversal of a relationship in the resulting bean objects there will be a performance hit.

The beans will be sorted in ascending of the field named for the orderFieldName parameter, unless that field is of a date type, in which case the order will be descending on that field.

This method should not be called by external clients. Call findIn<field-name>Order() on the home interface instead.

This method is called by the implementation of an entity bean's home interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - an entity bean prototype for those beans which will be selected from persistent storage.

constrainedFields - determines how the selection is made.

orderFieldName - the field to order the results on.

Returns:

the entity beans selected.

Throws:

EJBException - the action failed unexpectedly.

selectAllOfEntityBeansInOrder

public Collection selectAllOfEntityBeansInOrder(EntityBean bean,
                                                Collection constrainedFields,
                                                String orderFieldName)
                                         throws EJBException

The immediate action of this method is to load many entity beans from persistent storage. The loading occurs immediately, even if a transaction is being managed for the calling thread. The data retrieved will not reflect changes stored but not yet committed.

The beans loaded will immediately load all the beans they are related to. This method therefore carries a higher time and space overhead than selectEntityBeans(), but may offer a performance benefit in the long run if all these relationships are likely to be used subsequently.

The beans will be sorted in ascending of the field named for the orderFieldName parameter, unless that field is of a date type, in which case the order will be descending on that field.

This method should not be called by external clients. Call findAllIn<field-name>Order() on the home interface instead.

This method is called by the implementation of an entity bean's home interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - an entity bean prototype for those beans which will be selected from persistent storage.

constrainedFields - determines how the beans will be selected.

orderFieldName - the field to order the results on.

Returns:

the entity beans selected.

Throws:

EJBException - the action failed unexpectedly.

selectSiameseBeanObjects

public Collection selectSiameseBeanObjects(String sqlQuery)

The immediate action of this method is to load many entity beans from persistent storage. The loading occurs immediately, even if a transaction is being managed for the calling thread. The data retrieved will not reflect changes stored but not yet committed.

Any relationships to other beans are populated with null values. The effect of this is that the bean objects created from the entity beans returned from this method will defer loading of any beans they are related to until these relationships are explored.

This method is only called by external clients who wish to perform a join across multiple tables in the database. The result set is parsed by the container to form groups of joined BeanObjects and orphaned fields, each such row constituting a siamese bean which is added to the returned collection. This parsing can only work when:

• You select all fields from all tables in a qualified form (and don't include any orphaned fields): e.g.
  "SELECT" [ "DISTINCT" | "ALL" ] "*" "FROM"
  { <table-name> [ "ON" ... ],
  "," | "INNER JOIN" | "LEFT JOIN" | "RIGHT JOIN" }
  "WHERE" ...
  { ( "UNION" | "UNION ALL" | "INTERSECT" | "EXCEPT" | "MINUS" )
  [ "CORRESPONDING BY" { <table-name> "." <column-name> } ]
  "SELECT" "*" "FROM" { <table-name> [ "ON" ... ],
  "," | "INNER JOIN" | "LEFT JOIN" | "RIGHT JOIN" }
  "WHERE" ... } "ORDER BY" ...
• You select all fields from selected tables in a qualified form (and all orphaned fields in the projection follow those fields selected from tables): e.g.
  "SELECT" [ "DISTINCT" [ "ON"
  { ( <table-name> "." <column-name> |
  <orphaned-field-name> ), "," } ] | "ALL" ]
  { ( <table-name> ".*" |
  <orphaned-field-expression> "AS" <orphaned-field-name> ), "," } "FROM"
  { <table-name> [ "ON" ... ],
  "," | "INNER JOIN" | "LEFT JOIN" | "RIGHT JOIN" }
  "WHERE" ...
  { ( "UNION" | "UNION ALL" | "INTERSECT" | "EXCEPT" | "MINUS" )
  [ "CORRESPONDING BY" { ( <table-name> "." <column-name>
  <orphaned-field-name> ), "," } ]
  "SELECT" { ( <table-name> ".*" |
  <orphaned-field-expression> ), "," } "FROM"
  { <table-name> [ "ON" ... ],
  "," | "INNER JOIN" | "LEFT JOIN" | "RIGHT JOIN" }
  "WHERE" ... } "ORDER BY" ...

Note: The meaning of DISTINCT may depend on the underlying MrDatabase implementation*. For queries using a set operator, both queries must return sets, so the keyword DISTINCT is implicit, and the keyword ALL must not be used in either query argument (except as part of the UNION ALL operator.) Similarly, the interaction between DISTINCT and CORRESPONDING BY may also depend on the underlying MrDatabase implementation.

* For example, the MrOracleDatabase implementation ensures uniqueness on the primary key fields of each bean type only. DISTINCT ON is not supported (by Oracle or by MrOracleDatabase) and neither is CORRESPONDING BY. Order of evaluation of queries connected by set operators is left-to-right. i.e. set operators have the same precedence as one another.

Parameters:

sqlQuery - the SQL statement specifying the tables to join and how they should be joined.

Returns:

the SiameseBeans selected.

Throws:

EJBException - the action failed unexpectedly.

loadEntityBean

public EntityBean loadEntityBean(EntityBean bean)
                          throws EJBException

The immediate action of this method is to refresh an entity bean from persistent storage. The refresh occurs immediately, even if a transaction is being managed for the calling thread. The data retrieved will not reflect changes stored but not yet committed. The effect is a selective rollback for this entity bean. However, if this bean has been stored during the course of the current transaction, the version stored at that point may still be committed unless a new version (such as the version resulting from this method) is stored subsequently.

This method should not be called by external clients. Call load() on the object interface instead.

This method is called by the implementation of an entity bean's local interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - the entity bean to load from persistent storage.

Returns:

the refreshed entity bean.

Throws:

EJBException - the action failed unexpectedly.

activateEntityBean

public EntityBean activateEntityBean(EntityBean bean)
                              throws EJBException

The immediate action of this method is to reactivate a bean after transmission across a communication link or storage in a file.

By default, all the related beans are also activated.

This method should not be called by external clients.

Parameters:

bean - the entity bean to activate.

Returns:

the activated entity bean.

Throws:

EJBException - the action failed unexpectedly.

activateEntityBean

public EntityBean activateEntityBean(EntityBean bean,
                                     boolean recurse)
                              throws EJBException

The immediate action of this method is to reactivate a bean after transmission across a communication link or storage in a file.

This method should not be called by external clients.

Parameters:

bean - the entity bean to activate.

recurse - true if related beans should also be activated.

Returns:

the activated entity bean.

Throws:

EJBException - the action failed unexpectedly.

activateEntityBean

public EntityBean activateEntityBean(MrEntityBean bean,
                                     boolean recurse,
                                     boolean cache)
                              throws EJBException

The immediate action of this method is to reactivate a bean after transmission across a communication link or storage in a file.

This method should not be called by external clients.

Parameters:

bean - the entity bean to activate.

recurse - true if related beans should also be activated.

cache - true if beans should be cached.

Returns:

the activated entity bean.

Throws:

EJBException - the action failed unexpectedly.

activateEntityBeanRelatives

protected void activateEntityBeanRelatives(EntityBean bean,
                                           boolean cache)

Internal utility method to activate entity beans related to this entity bean.

Parameters:

bean - the entity bean whose relatives are to be activated.

cache - true if beans should be cached.

passivateEntityBean

public EntityBean passivateEntityBean(EntityBean bean)
                               throws EJBException

The immediate action of this method is to passivate a bean ready for transmission across a communication link or storage in a file.

By default, all the related beans are also passivated.

This method should not be called by external clients.

Parameters:

bean - the entity bean to passivate.

Returns:

the passivated entity bean.

Throws:

EJBException - the action failed unexpectedly.

passivateEntityBean

public EntityBean passivateEntityBean(EntityBean bean,
                                      boolean recurse)
                               throws EJBException

The immediate action of this method is to passivate a bean ready for transmission across a communication link or storage in a file.

This method should not be called by external clients.

Parameters:

bean - the entity bean to passivate.

recurse - true if related beans should also be passivated.

Returns:

the passivated entity bean.

Throws:

EJBException - the action failed unexpectedly.

passivateEntityBeanRelatives

protected void passivateEntityBeanRelatives(EntityBean bean)

Internal utility method to passivate entity beans related to this entity bean.

Parameters:

bean - the entity bean whose relatives are to be passivated.

storeEntityBean

public EntityBean storeEntityBean(EntityBean bean,
                                  boolean cloned)
                           throws EJBException

The eventual action of this method is to update an entity bean in persistent storage. This action, if a transaction is being managed for the calling thread, may not occur if this transaction is not subsequently committed or rolled back. If a transaction is not being managed for the calling thread, the update occurs immediately.

This method should not be called by external clients. Call store() on the object interface instead.

This method is called by the implementation of an entity bean's local interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - the entity bean to store to persistent storage.

cloned - true if the bean being stored is a clone, false otherwise.

Returns:

the updated entity bean, or null if in transaction context.

Throws:

EJBException - the action failed unexpectedly.

removeEntityBean

public EntityBean removeEntityBean(EntityBean bean,
                                   boolean cloned)
                            throws EJBException,
                                   RemoveException

The eventual action of this method is to delete an entity bean from persistent storage. This action, if a transaction is being managed for the calling thread, may not occur if this transaction is not subsequently committed or rolled back. If a transaction is not being managed for the calling thread, the removal occurs immediately.

This method should not be called by external clients. Call remove() on the home or object interface instead.

This method is called by the implementation of an entity bean's local and home interfaces to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - the entity bean to remove from persistent storage.

cloned - true if the bean being stored is a clone, false otherwise.

Returns:

the removed entity bean.

Throws:

EJBException - the action failed unexpectedly.

RemoveException

wipeEntityBeans

public WipeResponse wipeEntityBeans(EntityBean bean,
                                    Collection constrainedFields)
                             throws EJBException,
                                    RemoveException

The eventual action of this method is to delete many entity beans from persistent storage. This action, if a transaction is being managed for the calling thread, may not occur if this transaction is not subsequently committed or rolled back. If a transaction is not being managed for the calling thread, the removal occurs immediately.

This method should not be called by external clients. Call findWhereFieldsEqual() on the home interface instead.

This method is called by the implementation of an entity bean's home interface to allow the communication with persistent storage to occur in a way appropriate for the prevailing Container subtype.

Parameters:

bean - an entity bean prototype for those beans which will be deleted from persistent storage.

constrainedFields - determines the beans to be deleted.

Returns:

the response to this command.

Throws:

EJBException - the action failed unexpectedly.

RemoveException

invokeMethodOfBeanObject

public InvokeResponse invokeMethodOfBeanObject(Method method,
                                               EntityBean bean,
                                               Object[] parameters)
                                        throws EJBException

The immediate action of this method is to execute a method of an entity bean on the server.

This method should not be called by external clients. Call invokeOnServer() on the object interface instead.

Parameters:

method - the method to invoke.

bean - the entity bean which is the invocation target.

parameters - the parameters to the method call.

Returns:

the response to this command.

Throws:

EJBException - the action failed unexpectedly.

invokeMethodOfHome

public InvokeResponse invokeMethodOfHome(Method method,
                                         EntityBean bean,
                                         Object[] parameters)
                                  throws EJBException

The immediate action of this method is to execute a method of a home interface on the server.

This method should not be called by external clients. Call invokeOnServer() on the home interface instead.

Parameters:

method - the method to invoke.

bean - the entity bean which is the invocation target.

parameters - the parameters to the method call.

Returns:

the response to this command.

Throws:

EJBException - the action failed unexpectedly.

lockHome

public LockResponse lockHome(EntityBean bean)
                      throws EJBException

The eventual action of this method is to lock the table associated with a particular home until the transaction has completed.

This method should not be called by external clients. Call lock() on the home interface instead.

Parameters:

bean - the entity bean which is representing the home.

Returns:

the response to this command.

Throws:

EJBException - the action failed unexpectedly.

logOnServer

public LogResponse logOnServer(String logMessage)
                        throws EJBException

The eventual action of this method is to place a log message in the server log file. This action will not occur if the transaction is rolled back at a point before the log message was written. If the transaction is never committed, the action will not occur either. If a transaction is not being managed for the calling thread, the logging action occurs immediately.

Parameters:

logMessage - the message to log.

Returns:

the response to this command.

Throws:

EJBException - the action failed unexpectedly.

flushBeans

public FlushResponse flushBeans(EntityBean bean)
                         throws EJBException

Ensures that beans of the specified type are removed from all caches.

This method should be called by external clients only when manually instructed to do so by the user. This method should not be called during normal system operations.

Parameters:

bean - an entity bean prototype for the beans which will be removed from caches.

Throws:

EJBException - the action failed.

heimlichServer

public HeimlichedObstruction heimlichServer(String serverDumpFilename)
                                     throws EJBException

Kills all running threads on the server, leaving it in an undefined state. The server may need to be forcibly shutdown after this action, as some data structures may be corrupt.

This method should be used for debugging purposes only to find where in the code thread deadlocks are occurring. This method is not the correct way to shutdown the server.

Parameters:

serverDumpFilename - a suggestion for the name of the file that the server should open to write the thread dumps to.

Throws:

EJBException - the action failed.

alertServer

public AlertResponse alertServer(int oldAlertStatus,
                                 int newAlertStatus)
                          throws EJBException

Throws:

EJBException

reportServerStatus

public StatusResponse reportServerStatus()
                                  throws EJBException

Throws:

EJBException

getIDForEntityBean

public String getIDForEntityBean(EntityBean bean)

This internal utility method returns an identifier for a bean based on its type and primary key.

It is not intended to be used by external clients.

Parameters:

bean - the entity bean to express an identifier for.

Returns:

an identifier for this entity bean.

getObjectIDForEntityBean

public String getObjectIDForEntityBean(EntityBean bean)

This internal utility method returns an identifier for a bean based on its type and primary key.

It is not intended to be used by external clients.

Parameters:

bean - the entity bean to express an identifier for.

Returns:

an identifier for a bean object corresponding to this entity bean.

setRollbackOnly

public void setRollbackOnly()

Ensures that the current transaction being managed for the calling thread can never be committed.

Specified by:

setRollbackOnly in interface UserTransaction

Throws:

IllegalStateException - if a transaction is not being managed for the calling thread.

setRollbackOnly

protected void setRollbackOnly(Object handle)

Ensures that the specified transaction can never be committed.

Parameters:

handle - the object which owns the transaction.

Throws:

IllegalStateException - if there is no such transaction.

getRollbackOnly

public boolean getRollbackOnly()

Returns true if the current transaction being managed for the calling thread will never be committed.

Returns:

true if the transaction for the current thread is marked for rollback.

getRollbackOnly

public boolean getRollbackOnly(Object handle)

Returns true if the specified transaction will never be committed.

Parameters:

handle - the object which owns the transaction.

Returns:

true if the specified transaction is marked for rollback.

commit

public void commit()
            throws RollbackException,
                   HeuristicMixedException

Complete the transaction being managed for the calling thread. When this method completes, the thread becomes associated with no transaction.

Specified by:

commit in interface UserTransaction

Throws:

RollbackException - the transaction has been rolled back rather than committed, probably because one of the commands in the transaction failed.

HeuristicMixedException - unauthorized commands in the transaction have been rolled back, but those that were authorized have been committed.

IllegalStateException - if a transaction is not being managed for the calling thread.

commit

protected void commit(Object handle)
               throws RollbackException,
                      HeuristicMixedException

Complete the given transaction.

When this method completes, the thread becomes associated with no transaction.

Parameters:

handle - the object which owns the transaction.

Throws:

RollbackException - the transaction has been rolled back rather than committed, probably because one of the commands in the transaction failed.

HeuristicMixedException - unauthorized commands in the transaction have been rolled back, but those that were authorized have been committed.

IllegalStateException - if a transaction is not being managed for the calling thread.

rollback

public void rollback()

Roll back the transaction associated with the calling thread. When this method completes, the thread becomes associated with no transaction.

Specified by:

rollback in interface UserTransaction

Throws:

IllegalStateException - if a transaction is not being managed for the calling thread.

rollback

protected void rollback(Object handle)

Roll back the given transaction. When this method completes, the thread becomes associated with no transaction.

Parameters:

handle - the object which owns the transaction.

Throws:

IllegalStateException - if a transaction is not being managed for the calling thread.

executeBatchFind

public void executeBatchFind()
                      throws EJBException

Executes a batch find operation.

Throws:

IllegalStateException - if a batch find is not being managed for the calling thread.

EJBException - if any of the commands in the batch fail.

getStatus

public int getStatus()

Obtain the status of the transaction associated with the calling thread.

Specified by:

getStatus in interface UserTransaction

Returns:

The transaction status. If no transaction is associated with the current thread, this method returns the Status.NoTransaction value.

getStatus

protected int getStatus(Object handle)

Obtain the status of the specified transaction.

Parameters:

handle - the object which owns the transaction.

Returns:

the transaction status or, if no transaction is associated with the given handle, the Status.NoTransaction value.

debugTransaction

public void debugTransaction()

Prints (if debugging is enabled) the contents of the current transaction for this thread.

doCommandInTransactionContext

protected Response doCommandInTransactionContext(Command command)
                                          throws EJBException

Internal method which executes a command (a) immediately if the calling thread has no defined transaction context or (b) at commit time if the calling thread is presently in the context of a transaction. The effect of a subsequent rollback is to cause this and all subsequent commands executed within the transaction context rolled back to not be executed.

Parameters:

command - the command to execute.

Returns:

a response to the command, if it was executed immediately; otherwise null is returned.

Throws:

EJBException

isCommandWhichExpectsNonPooledBean

protected boolean isCommandWhichExpectsNonPooledBean(Command command)

Internal utility method to determine if this command takes a non-pooled bean (i.e. a bean with identity) as an argument.

Parameters:

command - the command instance.

Returns:

true if the command instance expects a non-pooled bean, false if it expects a pooled bean or does not depend on a bean.

copyUpdateStampFromEntityBeanToBean

public void copyUpdateStampFromEntityBeanToBean(EntityBean sourceBean,
                                                EntityBean objectBean)

Internal utility method sets the last update date/time and username field values for one entity bean to those of another.

Parameters:

sourceBean - the bean with the stamp fields to copy.

objectBean - the bean with the stamp fields to replace.

nullifyRelationships

public EntityBean nullifyRelationships(EntityBean bean)

This internal utility method sets the relationships of a "Thin" entity bean to null.

Useful before serializing a bean in some situations.

Parameters:

bean - the "Thin" entity bean to nullify relationships for.

Returns:

the "Thin" entity bean so modified.

storeBeanObjectRelatives

public void storeBeanObjectRelatives(BeanWrapper beanObject)
                              throws EJBException

Internal utility method to activate the store() methods of all bean objects related to this bean object.

External clients should not call this method. Instead they should call the storeWithRelated() method of the bean's component interface instead.

Parameters:

beanObject - the bean object whose relatives are to be stored.

Throws:

EJBException

removeNonRelativesFromBeanObjectRelatives

public void removeNonRelativesFromBeanObjectRelatives(BeanWrapper beanObject)
                                               throws EJBException,
                                                      RemoveException

Internal utility method to activate the removeUnrelated() methods of all bean objects related to this bean object.

External clients should not call this method. Instead they should call the removeUnrelatedFromRelated() method of the bean's component interface instead.

Parameters:

beanObject - the bean object whose relatives are to be stored.

Throws:

EJBException

RemoveException

areBeanObjectRelativesPersistent

public boolean areBeanObjectRelativesPersistent(BeanWrapper beanObject,
                                                boolean relativesPersistent)
                                         throws EJBException

Internal utility method to determine if the direct and indirect relationships of a bean object are persistent.

External clients should not call this method. Instead they should call the areRelativesPersistent() method of the bean's component interface instead.

Parameters:

beanObject - the bean object whose relatives are to be examined.

relativesPersistent - false if the direct relationships of this bean object are not persistent, true otherwise.

Returns:

false if any of this bean object's direct or indirect relationships aren't reflected in persistent storage, true otherwise.

Throws:

EJBException

removeNonRelatives

public void removeNonRelatives(Collection beanObjects)
                        throws EJBException,
                               RemoveException

Internal utility method to activate the removeUnrelated() and remove() methods of a list of bean objects which are to be unrelated from another bean object.

External clients should not call this method. Instead they should call the removeUnrelated() method of an appropriate bean's component interface instead.

Parameters:

beanObjects - the bean objects which are to be unrelated from another bean object.

Throws:

EJBException

RemoveException

removeNonRelativesFromBeanObjectNonRelatives

public void removeNonRelativesFromBeanObjectNonRelatives(Collection beanObjects)
                                                  throws EJBException,
                                                         RemoveException

Internal utility method to activate the removeUnrelatedFromRelated() and removeUnrelated() methods of a list of bean objects which are to be unrelated from another bean object.

External clients should not call this method. Instead they should call the removeUnrelatedFromRelated() method of an appropriate bean's component interface instead.

Parameters:

beanObjects - the bean objects which are to be unrelated from another bean object.

Throws:

EJBException

RemoveException

restoreNonRelativesToBeanObjectRelatives

public Map restoreNonRelativesToBeanObjectRelatives(Collection beanObjects)
                                             throws EJBException

Internal utility method to activate the restoreUnrelated() and restoreUnrelatedToRelated() methods of a list of bean objects which are to be rerelated to another bean object.

External clients should not call this method.

Parameters:

beanObjects - the bean objects which are to be rerelated to another bean object.

Returns:

a record of the rerelated beans.

Throws:

EJBException

unrelateGivenRelativesFromBeanObjectRelatives

public void unrelateGivenRelativesFromBeanObjectRelatives(Collection relatives,
                                                          Map keyEntryTable)
                                                   throws EJBException

Internal utility method to activate the unrelateAllInFlatMap() and unrelateAllInNestedMapFromRelated() methods of a map of bean objects which are to be re-unrelated from the given relatives.

External clients should not call this method.

Parameters:

relatives - the bean objects which will be selected from.

keyEntryTable - describes the bean objects which are to be re-unrelated fromthe given relatives.

Throws:

EJBException

executeRetrieveMethodCallsForBeanObject

public void executeRetrieveMethodCallsForBeanObject(BeanWrapper beanObject)
                                             throws EJBException

Internal utility method to invoke methods starting with the word "retrieve" in a particular bean object.

Parameters:

beanObject - the bean object whose retrieve methods are to be invoked.

Throws:

EJBException

executeRetrieveMethodCallsForBeanObjects

public Collection executeRetrieveMethodCallsForBeanObjects(Collection beanObjects)
                                                    throws EJBException

Internal utility method to invoke methods starting with the word "retrieve" in a collection of bean objects.

Parameters:

beanObjects - the bean objects whose retrieve methods are to be invoked.

Returns:

the collection of bean objects.

Throws:

EJBException

executeRetrieveMethodCallsForBeanObjects

public Map executeRetrieveMethodCallsForBeanObjects(Map beanObjects)
                                             throws EJBException

Internal utility method to invoke methods starting with the word "retrieve" in a map of bean objects.

Parameters:

beanObjects - the bean objects whose retrieve methods are to be invoked.

Returns:

the map of bean objects.

Throws:

EJBException

batchRetrieveMethodCallsForBeanObject

protected Batch batchRetrieveMethodCallsForBeanObject(Batch batch,
                                                      BeanWrapper beanObject)
                                               throws EJBException

Internal utility method to batch calls to the methods starting with the word "retrieve" in a particular bean object.

Parameters:

beanObject - the bean object whose retrieve methods are to be invoked.

Throws:

EJBException

batchRetrieveMethodCallsForBeanObjects

protected Batch batchRetrieveMethodCallsForBeanObjects(Batch batch,
                                                       Collection beanObjects)
                                                throws EJBException

Internal utility method to batch calls to the methods starting with the word "retrieve" in a collection of bean objects.

Parameters:

beanObjects - the bean objects whose retrieve methods are to be invoked.

Throws:

EJBException

convertPrototypeFromDefaultDatabaseWildcards

public EJBLocalObject convertPrototypeFromDefaultDatabaseWildcards(EJBLocalObject beanObject)

Takes a prototype bean, and transforms String fields containing the default database wildcards into Strings containing the wildcards appropriate for the MrDatabase instance associated with this Container.

Parameters:

beanObject - the prototype bean object to transform.

Returns:

the transformed prototype bean.

convertPrototypeToDefaultDatabaseWildcards

public EJBLocalObject convertPrototypeToDefaultDatabaseWildcards(EJBLocalObject beanObject)

Takes a prototype bean, and transforms String fields containing the database wildcards appropriate for the MrDatabase instance associated with this Container into Strings containing the default wildcards.

Parameters:

beanObject - the prototype bean object to transform.

Returns:

the transformed prototype bean.

doCommands

public abstract Collection doCommands(Collection commands)
                               throws EJBException

Internal method to perform a batch of commands.

This method is not intended to be used by external clients.

Parameters:

commands - the batch of commands.

Returns:

the batch of responses.

Throws:

EJBException

getBadCommandIndex

public int getBadCommandIndex(boolean remove)

Gives the index of the last command that failed during a doCommands() call for the current thread.

Parameters:

remove - true if the command index should be forgotten after the call.

Returns:

the index of the command that failed, or -1 if no index is recorded.

doCommand

public Response doCommand(Command command)
                   throws EJBException

Internal method to perform a single command immediately.

This method is not intended to be used by external clients.

Parameters:

command - the command to be executed.

Returns:

a response to the command executed.

Throws:

EJBException

doCommand

public abstract Response doCommand(Command command,
                                   boolean oneOff)
                            throws EJBException

Internal method to perform a single command immediately.

This method is not intended to be used by external clients.

Parameters:

command - the command to be executed.

oneOff - true if this command is not associated with a transaction, false otherwise.

Returns:

a response to the command executed.

Throws:

EJBException

equals

public boolean equals(Object another)

Does a crude test to check if two Containers contain the same types.

Specified by:

equals in interface Principal

Overrides:

equals in class Object

Parameters:

another - the object to compare with this container.

Returns:

true if this container contains the same types as another, false otherwise.

getName

public String getName()

Returns a dummy principal name for this container.

Specified by:

getName in interface Principal

Returns:

a largely meaningless name.

toString

public String toString()

Returns a string representation of this container.

Specified by:

toString in interface Principal

Overrides:

toString in class Object

Returns:

a string representation of this container.

hashCode

public int hashCode()

Returns a hashcode for this container.

Specified by:

hashCode in interface Principal

Overrides:

hashCode in class Object

Returns:

a hashcode for this container.