com.jadeworld.jade.rootschema
Class Object

java.lang.Object
  com.jadeworld.jade.rootschema.Object

Direct Known Subclasses:

Application, Collection, Global, Iterator, JadeBytes, JadeDynamicObject, Lock, Node, Notification, Process, Schema, System, WebSession

public class Object
extends java.lang.Object

The base class for all JADE-derived classes.

Field Summary

long	oid Holds the encoded JADE oid (object identifier).

Constructor Summary

Object()

Method Summary

boolean	changeObjectVolatility(Object object, int volatility, boolean conditional) Changes the volatility state of the persistent object specified in the object parameter.
java.util.Calendar	creationTime() Returns the date and time at which the receiver was created as a date/time.
int	edition(Object entity) Returns the JADE object edition value.
boolean	equals(java.lang.Object obj) Equality test.
void	exclusiveLock(Object entity) Attempts to acquire an exclusive lock on the object specified in the entity parameter.
int	getClassNumberForObject(Object obj) Returns the number of the class specified in the obj parameter, even if this object is no longer valid.
java.math.BigDecimal	getInstanceIdForObject(Object obj) Returns the instance identifier of the object specified in the obj parameter, even if this object is no longer valid.
void	getLockStatus(Object target, int lockType, int lockDuration, Process lockedBy) Returns the lock type and the lock duration of the current JADE process locks for the object specified in the target parameter.
java.lang.String	getName() Returns a string containing the class of the receiver.
java.lang.String	getObjectStringForObject(Object object) Returns a string representing the object specified in the obj parameter.
int	getObjectVolatility(Object object) Returns the volatility state of the persistent object specified in the object parameter.
java.lang.String	getOidString() Returns the object identifier (oid) of the receiver in a string format, even if this object is no longer valid.
java.lang.String	getOidStringForObject(Object obj) Returns a string format of the object identifier (oid) specified in the obj parameter.
java.lang.Object	getPropertyValue(java.lang.String name) Returns the value of the property specified in the name parameter.
int	hashCode() Hash code calculation.
boolean	hasMembers(Collection coll) Returns true if the collection specified in the coll parameter has any members or it returns false if the collection is empty.
boolean	isImportedObject(Object object) Returns true if the object specified in the obj parameter is an instance of an imported class or it returns false if it is not an instance of an imported class.
boolean	isKindOf(java.lang.Class classObject) Returns true if the receiver is an instance of the class specified in the classObject parameter.
boolean	isLockedByMe(Object target) Returns true if the current process has the parameter object locked.
boolean	isObjectFrozen(Object object) Returns true if the volatility state of the object specified in the object parameter is frozen (that is, cannot be updated).
boolean	isObjectNonSharedTransient(Object obj) Returns true if the object specified in the obj parameter is a non-shared transient instance or it returns false if it is not, even if this object is no longer valid.
boolean	isObjectPersistent(Object obj) Returns true if the object specified in the obj parameter is a persistent instance or it returns false if it is not.
boolean	isObjectSharedTransient(Object obj) Returns true if the object specified in the obj parameter is a shared transient instance or it returns false if it is not.
boolean	isObjectStable(Object object) Returns true if the volatility state of the object specified in the object parameter is stable (that is, it is not updated frequently).
boolean	isObjectTransient(Object obj) Returns true if the object specified in the obj parameter is a shared or a non-shared transient instance, or it returns false if it is not.
boolean	isObjectVolatile(Object object) Returns true if the volatility state of the object specified in the object parameter is volatile (that is, it is often updated, and is locked and unlocked in the usual way).
boolean	isSharedTransient() Returns true if the receiver is a shared transient object.
boolean	isSystemObject() Returns true if the receiver is an instance of a Jade system class.
boolean	isTransient() Returns true if the receiver is a transient object.
int	latestEdition() Returns the most-recently committed edition of the receiver as an integer value.
void	lock(Object entity, int lockType, int lockDuration, int timeout) Acquires the type of lock specified in the lockType parameter for the object specified in the entity parameter.
void	makeObjectFrozen(Object object) Conditionally changes the volatility state of the persistent object specified in the object parameter to frozen.
void	makeObjectStable(Object object) The makeObjectStable method of the Object class changes the volatility state of the persistent object specified in the object parameter to stable.
void	makeObjectVolatile(Object object) The makeObjectVolatile method of the Object class changes the volatility state of the persistent object specified in the object parameter to volatile.
void	reserveLock(Object entity) Attempts to acquire a reserve lock on the object specified in the lockTarget parameter.
void	sdeCauseEvent(int eventType, boolean immediate, java.lang.String userInfo)
void	sdsCauseEvent(int eventType, boolean immediate, java.lang.String userInfo)
void	setPropertyValue(java.lang.String name, java.lang.String value) Sets the property of the receiver specified in the name parameter to the value specified in the value parameter.
void	sharedLock(Object entity) Attempts to acquire a shared lock on the object specified in the lockTarget parameter.
java.lang.String	toString() Returns the value when an object instance is displayed.
boolean	tryLock(Object entity, int lockType, int lockDuration, int timeout) Attempts to acquire a lock of the specified type and duration, waiting up to the timeout period (in milliseconds) to obtain the lock on the object specified in the entity parameter.
void	unlock(Object entity) Removes the current lock from the object specified in the entity parameter.
void	updateObjectEdition(Object object) Update the object edition somehow.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

oid

public long oid

Holds the encoded JADE oid (object identifier). All JADE objects have a unique oid that identifies the object instance. This property is the link between the Java object and the equivalent JADE object.

Constructor Detail

Object

public Object()

Method Detail

equals

public boolean equals(java.lang.Object obj)

Equality test. Uses the oid field.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Hash code calculation. Uses the oid value.

Overrides:

hashCode in class java.lang.Object

Returns:

Hash code of object

toString

public java.lang.String toString()

Returns the value when an object instance is displayed.

Overrides:

toString in class java.lang.Object

Returns:

Class name and oid value.

changeObjectVolatility

public boolean changeObjectVolatility(Object object,
                                      int volatility,
                                      boolean conditional)

Changes the volatility state of the persistent object specified in the object parameter. (You can change the volatility state only of persistent objects. All transient objects are considered volatile.) For details, see "Cache Concurrency", in Chapter 9 of your JADE Developer's Reference.

Use the volatility parameter to specify the volatility state that you require, represented by one of the following global constants in the ObjectVolatility category.

 Global Constant Integer Value Description

 Volatility_Frozen #04 Object is frozen (that is, it is not updated)

 Volatility_Stable #08 Object is stable (that is, it is updated infrequently)

 Volatility_Volatile #00 Object is volatile (that is, it is updated often)

As object volatility state is conditional by default, a frozen object can be updated only by first changing its volatility to Volatility_Stable or Volatility_Volatile.

Use the conditional parameter to specify whether the change is conditional or unconditional. Set the value of this parameter to false if the change is unconditional; that is, the change takes place even if an attempt is made to change the volatility of a frozen object that is being used by any other process.

Parameters:

object - The object whose state is to be changed

volatility - Option as above

conditional - See above

creationTime

public java.util.Calendar creationTime()

Returns the date and time at which the receiver was created as a date/time.

Returns:

Object creation date and time.

edition

public int edition(Object entity)

Returns the JADE object edition value. Each JADE object has an edition of 1 when it is created. The edition is incremented each time that the object is updated in a specified transaction but only once for each transaction, and is used for buffer (cache) synchronization.

Parameters:

entity - The JADE object to return the edition value for.

Returns:

The edition of the corresponding JADE object

exclusiveLock

public void exclusiveLock(Object entity)

Attempts to acquire an exclusive lock on the object specified in the entity parameter.
If another process has a conflicting lock, the process waits until the lock is released. The object is exclusively locked for the duration of the transaction.
For details about exclusive locks, see "Locking Objects", in Chapter 9 of your JADE Developers Reference.

Parameters:

entity - The JADE entity to apply the exclusive lock to.

getClassNumberForObject

public int getClassNumberForObject(Object obj)

Returns the number of the class specified in the obj parameter, even if this object is no longer valid.

Parameters:

obj - The object to get the class number for.

Returns:

The JADE class number for this object.

getInstanceIdForObject

public java.math.BigDecimal getInstanceIdForObject(Object obj)

Returns the instance identifier of the object specified in the obj parameter, even if this object is no longer valid.
Note The decimal value returned by this method avoids problems caused by negative numbers for large values.

Parameters:

obj - The object to get the instance id of

Returns:

The JADE instance id of this object.

getLockStatus

public void getLockStatus(Object target,
                          int lockType,
                          int lockDuration,
                          Process lockedBy)

Returns the lock type and the lock duration of the current JADE process locks for the object specified in the target parameter. The lockedBy parameter contains the current process. This method returns only the lock status of an object locked by the current process. The current JADE process instance can be obtained by the EntityManager getProcess() method.

Parameters:

target - The object to check for lock status.

lockType - Returns the lock type (see JadeConstants).

lockDuration - Returns the lock duration (see JadeConstants).

lockedBy - The JADE process instance.

getName

public java.lang.String getName()

Returns a string containing the class of the receiver. In this default implementation of the getName method, the description consists of the name of the class of the receiver.
A subclass can reimplement the getName method to provide a more-informative description appropriate to that class.

Returns:

The object name.

getObjectStringForObject

public java.lang.String getObjectStringForObject(Object object)

Returns a string representing the object specified in the obj parameter. This method is the inverse of the String primitive type asObject method. The returned string consists of the oid-like string based on class numbers, followed by an optional lifetime indication.
The form of the oid-like string can be one of the following.

• class-number.instId
• class-number.instId.parent-class-number
• class-number.instId.parent-class-number.subLevel.subId

Parameters:

object - The object to return the string for.

getObjectVolatility

public int getObjectVolatility(Object object)

Returns the volatility state of the persistent object specified in the object parameter. For details, see "Cache Concurrency", in Chapter 9 of your JADE Developer's Reference.

Use the getObjectVolatility method to determine the volatility state of a persistent object. (All transient objects are considered volatile.) This method returns the volatility state of the object, represented by one of the following global constants in the ObjectVolatility category.

 Global Constant Integer Value Description

 Volatility_Frozen #04 Object is frozen (that is, it is not updated)

 Volatility_Stable #08 Object is stable (that is, it is updated infrequently)

 Volatility_Volatile #00 Object is volatile (that is, it is updated often)

Parameters:

object - The object to return the volatility state for.

getOidString

public java.lang.String getOidString()

Returns the object identifier (oid) of the receiver in a string format, even if this object is no longer valid.

The formats of the object id for shared and exclusive references are listed in the following table.

 Type of Reference Format Example
 Shared class-id.instance-id "305.1208"
 Exclusive class-id.instance-id.parent-class-id.sublevel.sub-id "66.101.305.2.1"
 

Tip When you already have the object, calling self.getOidStringForObject(self) is significantly faster than calling the getOidString method.

Returns:

The JADE object id string value.

getOidStringForObject

public java.lang.String getOidStringForObject(Object obj)

Returns a string format of the object identifier (oid) specified in the obj parameter. This method is the inverse of the String primitive type asOid method.

The formats of the object id for shared and exclusive references are listed in the following table.

Type of Reference Format Example
 Shared class-id.instance-id "305.1208"
 Exclusive class-id.instance-id.parent-class-id.sublevel.sub-id "66.101.305.2.1"

Caution For instances of classes with large class numbers, the class identifier and parent class identifier parts of the string are not the same as the class number returned by the Object class getObjectStringForObject(com.jadeworld.jade.rootschema.Object) method.

For details about returning a string of a specified object as an oid-like string based on class numbers and a following optional lifetime indication, see the Object class getObjectStringForObject(com.jadeworld.jade.rootschema.Object) method.

Parameters:

obj - The object to return the oid string for.

Returns:

The oid string for this object.

getPropertyValue

public java.lang.Object getPropertyValue(java.lang.String name)

Returns the value of the property specified in the name parameter. The return result can be assigned to a variable of type Object or it can be converted to a specific primitive type or class if the type is known. If the property name is invalid, an exception is raised.

Parameters:

name - The JADE name of the property.

Returns:

The value of this property in the current object instance.

hasMembers

public boolean hasMembers(Collection coll)

Returns true if the collection specified in the coll parameter has any members or it returns false if the collection is empty.

The specified collection must be a persistent instance of an exclusive collection for which the Delete when emptied check box is checked on the Tuning sheet of the Define Class dialog. (For details, see "Tuning Collection Classes" under "Defining Your Own Classes", in Chapter 3 of your JADE Users Guide.)

If you call this method in a condition used as a constraint, the value of the coll parameter must be an unqualified reference of the receiver (that is, an exclusive collection defined on the receiver).

An exception is raised if you call this method for a transient collection instance or for a class that does not have the Delete when emptied check box on the Tuning sheet of the Define Class dialog checked.

Parameters:

coll - The collection to be checked.

Returns:

true if the collection has any member instances or if it is empty.

isImportedObject

public boolean isImportedObject(Object object)

Returns true if the object specified in the obj parameter is an instance of an imported class or it returns false if it is not an instance of an imported class.

Parameters:

object - The object to be checked.

Returns:

true if this object is an imported class.

isKindOf

public boolean isKindOf(java.lang.Class classObject)

Returns true if the receiver is an instance of the class specified in the classObject parameter.

This method returns false if the receiver is not an instance of the specified class. (Use the hasInstance method of the Class class to check if an instance of a class exists or it has been an instance of the class, without causing an exception if the reference is invalid.)

isLockedByMe

public boolean isLockedByMe(Object target)

Returns true if the current process has the parameter object locked.

Parameters:

target - The JADE entity to do the lock check on.

Returns:

true if this entity is locked by me; otherwise false.

isObjectFrozen

public boolean isObjectFrozen(Object object)

Returns true if the volatility state of the object specified in the object parameter is frozen (that is, cannot be updated). A frozen object can be updated only by first changing its volatility to Volatility_Stable or Volatility_Volatile.

Parameters:

object - The object to be checked.

Returns:

true if the object is frozen.

isObjectNonSharedTransient

public boolean isObjectNonSharedTransient(Object obj)

Returns true if the object specified in the obj parameter is a non-shared transient instance or it returns false if it is not, even if this object is no longer valid.

Parameters:

obj - The object to be checked.

Returns:

true if the object is a non-shared transient instance.

isObjectPersistent

public boolean isObjectPersistent(Object obj)

Returns true if the object specified in the obj parameter is a persistent instance or it returns false if it is not.

Parameters:

obj - The object to be checked.

Returns:

true if the object is a persistent instance.

isObjectSharedTransient

public boolean isObjectSharedTransient(Object obj)

Returns true if the object specified in the obj parameter is a shared transient instance or it returns false if it is not.

Parameters:

obj - The object to be checked.

Returns:

true if the object is a shared transient instance.

isObjectStable

public boolean isObjectStable(Object object)

Returns true if the volatility state of the object specified in the object parameter is stable (that is, it is not updated frequently).

Parameters:

object - The object to be checked.

Returns:

true if the object is stable.

isObjectTransient

public boolean isObjectTransient(Object obj)

Returns true if the object specified in the obj parameter is a shared or a non-shared transient instance, or it returns false if it is not.

Parameters:

obj - The object to be checked.

Returns:

true if the object is a transient instance.

isObjectVolatile

public boolean isObjectVolatile(Object object)

Returns true if the volatility state of the object specified in the object parameter is volatile (that is, it is often updated, and is locked and unlocked in the usual way).

Parameters:

object - The object to be checked.

Returns:

true if the object is volatile.

isSharedTransient

public boolean isSharedTransient()

Returns true if the receiver is a shared transient object. This method returns false if the receiver is a non-shared transient object or a persistent object.

Returns:

true if the object is a shared transient instance.

isSystemObject

public boolean isSystemObject()

Returns true if the receiver is an instance of a Jade system class.

Returns:

true if the object is is an instance of a system class.

isTransient

public boolean isTransient()

Returns true if the receiver is a transient object. This method returns false if the receiver is a persistent object.

Returns:

true if the object is a transient instance.

latestEdition

public int latestEdition()

Returns the most-recently committed edition of the receiver as an integer value. For example, if you are using edition 4 of an object and the object has been updated twice by other users or methods so that it now has an edition of 6, edition 6 is the edition that is returned with the latestEdition method.

If the receiver of the latestEdition method is being updated by the same process, the updated edition is returned. Other processes will instead have the most-recently committed edition returned.

Returns:

The latest edition of this JADE object.

lock

public void lock(Object entity,
                 int lockType,
                 int lockDuration,
                 int timeout)

Acquires the type of lock specified in the lockType parameter for the object specified in the entity parameter. The lockType is one of the com.jadeworld.jade.JadeConstants SHARE_LOCK (1), RESERVE_LOCK (2), or EXCLUSIVE_LOCK (3). The lockDuration is one of the com.jadeworld.jade.JadeConstants LOCK_TIMEOUT_IMMEDIATE (-1), LOCK_TIMEOUT_SERVER_DEFINED (0), or LOCK_TIMEOUT_INFINITE (Integer.MAX_VALUE).

Parameters:

entity - The JADE object to be locked.

lockType - The type of lock.

lockDuration - The duration of the lock.

timeout - The number of milliseconds for the timeout.

makeObjectFrozen

public void makeObjectFrozen(Object object)

Conditionally changes the volatility state of the persistent object specified in the object parameter to frozen. (Alternatively, you can call the changeObjectVolatility(com.jadeworld.jade.rootschema.Object, int, boolean) method to change the volatility state of an object.)

For details, see "Cache Concurrency", in Chapter 9 of your JADE Developer's Reference.

A frozen object can be updated only by first changing its volatility to stable or to volatile (that is, by calling the makeObjectStable or makeObjectVolatile method).

Parameters:

object - The object to change the volatility state to frozen.

makeObjectStable

public void makeObjectStable(Object object)

The makeObjectStable method of the Object class changes the volatility state of the persistent object specified in the object parameter to stable. (Alternatively, you can call the changeObjectVolatility method to change the volatility state of an object.)

For details, see "Cache Concurrency", in Chapter 9 of your JADE Developer's Reference.

When attempting to change the volatility of a frozen object, an exception is raised if the specified object is being used by any process other than the process invoking the method.

A frozen object can be updated only by first changing its volatility to stable or to volatile (that is, by calling the makeObjectStable or makeObjectVolatile method).

Parameters:

object - The object to change the volatility state to stable.

makeObjectVolatile

public void makeObjectVolatile(Object object)

The makeObjectVolatile method of the Object class changes the volatility state of the persistent object specified in the object parameter to volatile. (Alternatively, you can call the changeObjectVolatility method to change the volatility state of an object.)

For details, see "Cache Concurrency", in Chapter 9 of your JADE Developer's Reference.

When attempting to change the volatility of a frozen object, an exception is raised if the specified object is being used by any process other than the process invoking the method.

Parameters:

object - The object to change the volatility state to volatile.

reserveLock

public void reserveLock(Object entity)

Attempts to acquire a reserve lock on the object specified in the lockTarget parameter.
If the object already has a reserve lock or exclusive lock, the process waits until the lock is released for default timeout. (For details, see "ServerTimeout" under "JADE Object Manager Server Section [JadeServer]", in your JADE Initialization File Reference.)
A reserve lock enables you to lock an object that you intend to update, when you want to minimize the time that it is locked with an exclusive lock. For more details, see "Locking Objects", in Chapter 9 of your JADE Developers Reference.

Parameters:

entity - The JADE object to be locked.

sdeCauseEvent

public void sdeCauseEvent(int eventType,
                          boolean immediate,
                          java.lang.String userInfo)

sdsCauseEvent

public void sdsCauseEvent(int eventType,
                          boolean immediate,
                          java.lang.String userInfo)

setPropertyValue

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

Sets the property of the receiver specified in the name parameter to the value specified in the value parameter. If the property specified in the name parameter is invalid, an exception is raised.

Note You should not use the setPropertyValue method as a replacement for direct assignment to a property when the property name is known at compile time, as it incurs additional overhead and prevents the compiler from checking the type compatibility of the value being assigned.
You should use it only in special cases when property names are determined at run time.

Parameters:

name - The JADE name of the object property.

value - The value to which this property is to be set.

sharedLock

public void sharedLock(Object entity)

Attempts to acquire a shared lock on the object specified in the lockTarget parameter. An object that is locked by a shared lock cannot be locked with an exclusive lock or updated by other processes, but it can be locked by another shared lock or a reserve lock.

Parameters:

entity - The object to be locked.

tryLock

public boolean tryLock(Object entity,
                       int lockType,
                       int lockDuration,
                       int timeout)

Attempts to acquire a lock of the specified type and duration, waiting up to the timeout period (in milliseconds) to obtain the lock on the object specified in the entity parameter. If the lock can be acquired, the method returns true. If the lock cannot be obtained, this method returns false and no lock exception is raised.
The lockType is one of the com.jadeworld.jade.JadeConstants SHARE_LOCK (1), RESERVE_LOCK (2), or EXCLUSIVE_LOCK (3)
The lockDuration is one of the com.jadeworld.jade.JadeConstants LOCK_TIMEOUT_IMMEDIATE (-1), LOCK_TIMEOUT_SERVER_DEFINED (0), or LOCK_TIMEOUT_INFINITE (Integer.MAX_VALUE)

Parameters:

entity - The JADE object to be locked.

lockType - The type of lock.

lockDuration - The duration of the lock.

timeout - The number of milliseconds for the timeout.

Returns:

true if the lock has been obained; otherwise false.

unlock

public void unlock(Object entity)

Removes the current lock from the object specified in the entity parameter. Objects that are manually unlocked after a beginLoad instruction or beginTransaction instruction are not unlocked until an endLoad, commitTransaction, or abortTransaction instruction is encountered. For more details, see "Locking Objects", in Chapter 9 of the JADE Developers Reference.

Parameters:

entity - The JADE object to be unlocked.

updateObjectEdition

public void updateObjectEdition(Object object)

Update the object edition somehow.

Parameters:

object - The object to be updated.