Package wt.fc

Provides high level datastore access by using the PersistenceManager (and server-side-only PersistenceManagerSvr) to find and manage Persistable objects.

See:
Description

Interface Summary

BinaryLink	Interfaces that represents an association between two objects.
BusinessInformation	Deprecated.
DatastoreArray	This interface provides an abstraction for a Datastore array.
DatastoreElement	This interface provides a common abstraction for all Datastore element types.
DatastoreSequence	This interface provides an abstraction for a Datastore sequence.
DatastoreStruct	This interface provides an abstraction for a Datastore sequence.
DatastoreTable	This interface provides an abstraction for a Datastore table.
DatastoreType	This interface specifies common behavior for a Datastore Type.
Evolvable	Supported API: true Extendable: true
FilterResultProcessor	This interface extends ResultProcessor to support methods for filtering results to an underlying ResultProcessor.
IdentificationObjectNamespace	Supported API: false Extendable: false
IdentificationObjectNamespaceDelegate	Supported API: false Extendable: false
Identified	Identified is the interface to be implemented by classes that have attribute or collection of attributes that distinguishes the object.
IdentityService	Remote interface with public identity service methods.
Link	Link is the interface that represents any kind of associations between two or more domain-specific objects.
LinkRoleIndicator
Named	A Named class has a name.
NetFactor	Interface which specifies basic characteristics of Windchill code generation classes.
ObjectMappable	Objects that implement ObjectMappable have code generated methods that enable them to go in and out of relational databases.
ObjectVectorIfc	Interface that specifies the APIs used to manipulate an object vector Supported API: true Extendable: false
Persistable	Objects that implement the Persistable interface are first class objects that may be targets of PersistenceManager operations.
PersistenceManager	The PersistenceManager interface identifies the set of methods that applications use to manage the persistent state of their business objects.
PersistenceManagerSvr	The PersistenceManagerSvr interface identifies the set of PersistentManager methods that are invokable only from classes running in the method server Supported API: true Extendable: false
QueryKey	Interface that defines the properties of an object that allow it to be queried out of persistent storage and to perform comparison operations against an object using those properties.
QueryStringDelegate	Supported API: false Extendable: false
ReferenceDelegate	Supported API: false Extendable: false
ReferentialIntegrityExceptionHandler	This interface specificies delegate methods for additional processing relateted to ReferentialIntegrityException.
ResultProcessor	Supported API: false Extendable: false
UniquelyIdentified	Interface that marks Identified classes for which the identity is subject to uniqueness constraint.
WTReference	Interface that defines the basic notion of holding a reference to a Persistable object.

Class Summary

AbstractDatastoreArray	This abstract class contains common implementation for a Datastore Type.
AbstractDatastoreStruct	This abstract class contains common implementation for a Datastore Type.
AbstractFilterResultProcessor	This abstract class provides implmentation for some common FilterResultProcessor methods.
ActionIconDelegate	Supported API: false Extendable: false
BasicObjectVector	This class implments a basic vector of objects and is used to hold query results.
BinaryLinkUtilities	Utility static methods for working with BinaryLink objects.
CachedObjectReference	Supported API: false Extendable: false
CachedObjectReference.Singleton
DynamicEnumType	Supported API: true Extendable: true
EnumeratedType	A type that has a defined list of valid values, which may change over time.
EnumeratedType.OrderOnDisplay
EnumeratedType.OrderOnOrder
EnumeratedTypeUtil	A set utility methods for working with EnumeratedTypes.
ETLocaleTool
EvolvableHelper	Facilitates special operations needed by objects that evolve during deserialization.
ExtendedPageResults	This class represents the persistent table used for storing extended paging results.
ExtendedPageResultsList	Supported API: false Extendable: false
ExtendedPageResultTable	Use the newExtendedPageResultTable static factory method(s), not the ExtendedPageResultTable constructor, to construct instances of this class.
ForeignKeyLink	Abstract class that represents an association between two Persistables where one of the objects persistently holds a reference to the other.
IconDelegate	Supported API: true Extendable: false
IconDelegateFactory	Supported API: true Extendable: false
IdentificationObject	The IdentificationObject is an abstract class that encapsulates information about the identity of a single class or a set of classes.
IdentityCollationKeyFactory	A collation key factory for Identified objects.
IdentityHelper	The IdentityHelper provides access to the identity service through its public 'service' member.
IdentityMigrateHelper	Provides migration with a way to assign values to restricted attributes
IdentityServiceEvent	The IdentityServiceEvent encapsulates identity change events.
IdentityServiceFwd	Remote interface with public identity service methods.
IdOidObject	This class represents a Datastore struct for an ID and ObjectIdentifier pair.
IdOidObjectList	This class represents a Datastore array for a list of ID and ObjectIdentifier pairs.
IDSequence	This class represents the datastore sequnce for generating ObjectIdentifier ID values.
IdUpdateCountObject	This class represents a Datastore struct containing an object's ID and update count.
IdUpdateCountObjectList	This class represents a Datastore array containing IdUpdateCountObject objects.
Item	Item is the abstract base class that represents discrete items that can be associated with an administrative domain and are directly subject to access control.
IteratedObjectVector	Supported API: false Extendable: false
LinkVector
LobLocator	LobLocator provides interfaces to store and retrieve large objects (LOBs) from a datastore.
ObjectIdentifier	ObjectIdentifier represents a unique identifier assigned to the object by the PersistenceManager when it saves a Persistable object to a datastore.
ObjectReference	Holds a reference to a Persistable object by means of the object's ObjectIdentifier.
ObjectReferenceDelegate	Supported API: false Extendable: false
ObjectReferenceQueryStringDelegate	Supported API: false Extendable: false
ObjectReferenceSearch	Extends the basic AttributeSearchSpecification class to support handling of an Object Reference.
ObjectReferenceSearchValue	Supported API: false Extendable: false
ObjectSetVector	Supported API: false Extendable: false
ObjectTable	A table of Persistable objects with support for maintaining a set of shared ObjectReference objects which may refer to objects in the table.
ObjectTable.OidArrayImpl
ObjectToObjectLink	Abstract class that represents an association between two Persistable objects.
ObjectVector	Supported API: false Extendable: false
ObjectVectorEnumerator	Supported API: false Extendable: false
OidObject	This class represents a Datastore struct for an ObjectIdentifier.
OidObjectList	Supported API: false Extendable: false
PageResults	This class represents the persistent table used for storing paging results.
PageResultsList	Supported API: false Extendable: false
PageResultTable	Use the newPageResultTable static factory method(s), not the PageResultTable constructor, to construct instances of this class.
PagingCleanup
PagingQueryResult	This class is a container of results returned from a query along with paging session information.
PagingQueueDriver
PagingSession	This class represents a persistent paging session.
PagingSessionHelper	This class provides static helper methods for managing PagingSessions.
PersistenceHelper	The class contains utility methods associated with the PersistenceManager.
PersistenceManagerEvent	Used to represent events occuring within the PersistenceManager.
PersistenceManagerFwd	The PersistenceManager interface identifies the set of methods that applications use to manage the persistent state of their business objects.
PersistenceServerHelper	This class implements helper methods for server side PersistenceManagerSvr operations.
PersistentReference	This class holds a WTReference in a persistant form regardless of the type of reference.
PersistentReferenceQueryStringDelegate	Supported API: false Extendable: false
PersistInfo	PersistInfo represents the information that must be maintained about a Persistable object.
QueryResult	The QueryResult class is a container of results returned from a query.
QueryResult.ChunkedExternalization	Class used when streaming large results set to overcome scalability limitations of object streams by resetting stream at reasonable intervals.
QueryResult.DuplicateStringEliminator	Class used to eliminate duplicate strings from large query result stream.
QueryStringDelegateFactory	Supported API: false Extendable: false
RawObject	Use the newRawObject static factory method(s), not the RawObject constructor, to construct instances of this class.
RawObjectList	Supported API: false Extendable: false
ReCreateSemanticKeys	This gets called immediately after all the SemanticKeys with no references are deleted.
ReferenceDelegateFactory	Supported API: false Extendable: false
ReferenceFactory	A factory for getting references and strings that refer to persistable objects.
ReferenceResolver	Uses introspection and reflection to find the best matching reference class for a given Persistable class.
RequiredBlobMigrator	This class implements a migrator to check Required BLOB columns to ensure that the column does not contain a valid BLOB with zero length.
RowObject	Use the newRowObject static factory method(s), not the RowObject constructor, to construct instances of this class.
RowObjectList	Supported API: false Extendable: false
SemanticKey	The SemanticKey class helps to ensure the uniqueness constraint on object's identity.
SequencePool	This class is used to manage a pool of sequence values obtained from a datastore seuqence.
SimpleLinkRoleIndicator
SourceLinkMapResultProcessor	The ResultProcessor creates a mapping of source QueryKeys and associated Link ObjectIdentifiers stored in a WTArrayList value.
StandardIdentityService	Standard implementation of the identity service.
StandardPersistenceManager	StandardPersistenceManager is a concrete persistent manager targeted for WTObject classes.
StandardPersistenceManager.AbstractInsertUpdateProcessor
StandardPersistenceManager.PersistInfoData
StandardPersistenceManager.ReferentialIntegrityValidator
StandardReferentialIntegrityExceptionHandler	The class implements a standard mechanism for building a single generic message for each referential integrity violation.
StreamObjectVector	Supported API: false Extendable: false
StringKey	Use the newStringKey static factory method(s), not the StringKey constructor, to construct instances of this class.
TableOfDate	Supported API: false Extendable: false
TableOfNumber	Supported API: false Extendable: false
TableOfVarchar2	Supported API: false Extendable: false
TheSemanticKeyTheUniquelyIdentified	Use the newTheSemanticKeyTheUniquelyIdentified static factory method(s), not the TheSemanticKeyTheUniquelyIdentified constructor, to construct instances of this class.
VersionReferenceDelegate	Supported API: false Extendable: false
VersionReferenceQueryStringDelegate	Supported API: false Extendable: false
WTCollectionRetrySingleProcessor	This class implments a Template Method design pattern for executing a multi-object operation such that if it fails with an exception, a new exception can be constructed that will indicate the exact objects that failed.
WTLargeStringSet	This class duplicates the behavior of WTStringSet, but does NOT limit the total number of bytes in the String's it contains.
WTObject	WTObject is the abstract base class for all domain-specific item and link classes.
WTObjectCounter
WTStringMap	WTStringMap class maps keys to values.
WTStringSet	This class represents sets of strings that are represented in the database as a comma separated list of the strings it contains.

Exception Summary

InvalidAttributeException	Supported API: true Extendable: false
InvalidNavigateSourceException	Supported API: true Extendable: false
InvalidRoleException	Supported API: true Extendable: false
ModificationNotAllowedException	Supported API: true Extendable: false
ObjectNoLongerExistsException	Supported API: true Extendable: false
ObjectNotForLinkException	Supported API: true Extendable: false
ReferentialIntegrityException	This exception is used to report exception information related to referential integrity violations.

Package wt.fc Description

Provides high level datastore access by using the PersistenceManager (and server-side-only PersistenceManagerSvr) to find and manage Persistable objects. Also, contains the IdentityService to manage Identified objects.

The PersistenceManager methods generally take Persistable objects as argument values and/or return them as results. Classes that implement Persistable have the necessary code generated to read and write data to and from the database and display its identity. Applications should access the PersistenceManager through a convenience class named PersistenceHelper. This class also contains methods for accessing Persistence information and other utility methods for common operations that use PersistenceManager. The PersistenceManager service implementation also supports event notification for most of its operations.

Events

The PersistenceManager service implementation dispatches the PersistenceManagerEvent for various operations. The types of events are defined as static fields on this class. The event target object can be a single Persistable, a WTCollection of Persistables, or a WTKeyedMap of Persistables. The actual event target object is based on the event type.

Store

Persistable objects are first created in memory and can then be persisted to the datastore using the methods PersistenceManager.store(wt.fc.Persistable) or PersistenceManager.store(wt.fc.collections.WTCollection). The general pattern for constructing a persistent business object is as follows.

1. Invoke the factory method to get a new business object.
2. Set the attribute values of the new object.
3. Invoke the store method to make the object persistent.

Example:

Customer c = Customer.newCustomer("Acme"); 
c.setPhone("555-1234");
c.setAddressUS(anAddress);
c = (Customer)PersistenceHelper.manager.store(c);

Customer.newCustomer("Acme") calls initialize("Acme"), whereas Customer c = new Customer() does not. Always construct business objects with the factory method created by system generation. Also, note that setting the local variable to the return value is important in programming the client because the underlying RMI makes copies of the objects referenced by the arguments of the method. This means that objects passed as arguments by the client in the create method are not changed by the operations that occur on the method server.

Modify

Persistable objects that have already been persisted can be modified in the datastore using the methods PersistenceManager.modify(wt.fc.Persistable) or PersistenceManager.modify(wt.fc.collections.WTCollection). The general pattern for modifying a persistent business object is as follows.

1. Obtain an updated reference to the business object.
2. Set the attribute values of the object.
3. Invoke the modify method to make the changes persistent.

Example:

Customer aCustomer = ...;   
aCustomer.setPhone("555-0000"); 
aCustomer = (Customer)PersistenceHelper.manager.modify(aCustomer);

Setting the local variable to the return value is important in programming the client because the underlying RMI makes copies of the objects referenced by the arguments of the method. This means that objects passed as arguments by the client in the create method are not changed by the operations that occur on the method server.

Delete

Persistable objects that have already been persisted can be deleted from the datastore using the methods PersistenceManager.delete(wt.fc.Persistable) or PersistenceManager.delete(wt.fc.collections.WTSet). In addition to deleting the object, the persistence service will also perform referential integrity processing. This processing is driven by the modeled associations and properties related to the target object. The Rose model properties affect this behavior.

Class Specification, Windchill Tab, Datastore Properties, RemoveEventParticipant

If true, then the persistence service is required to dispatch appropriate events (e.g. REMOVE, CLEANUP_LINK, etc.) when an object of this type is involved in a delete operation. If false, then the persistence service can take advantage of this information to use a more efficient implementation (e.g. database referential integrity constraints, database triggers, etc.). The default value is true. The property can be set to “true” or “false” on a sub-class if it is not explicitly set on the parent. The attribute can be set to “true” on a sub-class if it is set to “false” on the parent. The attribute cannot be set to “false” on a sub-class if it is set to “true” on the parent.

Class Specification, Windchill A/B Tab, Datastore Properties, Owner

If true, then the persistence service will remove the link object associated with the deleted object. If false, then the persistence service does not implicitly remove the link object when the object is removed. However, the persistence service will verify that this association does not exist before the transaction commits. This means that the validation will not occur until a commit to the outer-most Transaction block that this delece operation occurs in. The default value is true and can be set to “true” or “false” independent of the parent class's setting.

Class Specification, Windchill A/B Tab, Datastore Properties, Cascade

If true, then the persistence layer will remove the role object for the corresponding association when the Link object is deleted. This occurs when the Link is removed via a direct call or via other referential integrity processing. If false, then the persistence layer does not remove the link object. The default value is false and can be set to “true” or “false” independent of the parent class's setting.

Refresh

Persistable objects can be retrieved from the datastore using PersistenceManager.refresh(Persistable obj,boolean fullRefresh,boolean inPlace,boolean lock) or PersistenceManagerSvr.restore(Persistable obj,boolean fullRestore,boolean inPlace,boolean checkFreshness,boolean lock). The refresh and restore methods ensure that neither the client nor the server has a stale business object.

The refresh method performs the following operations.

1. Ensures the object is already persistent.
2. Retrieves the state for the object from the database. All persistent attributes are retrieved, including values from autonavigated relationships.
3. Ensures the user is allowed to see the object, given its state.
4. Returns the object to the caller.

Setting the local variable to the return value is important in programming the client because the underlying RMI makes copies of the objects referenced by the arguments of the method. This means that objects passed as arguments by the client in the refresh method are not changed by the operations that occur on the method server.

Client code typically provides mechanisms that let you decide when business information should be refreshed. Server code should refresh the business object before performing any significant operation on that object. There is, however, one important exception to this rule: do not refresh the target object of an event in a service event listener and then subsequently update or modify the object. Because the refresh method actually returns a new object, the update count of the event’s target object will not be incremented when the update operation is called. Then, when any subsequent listeners are notified of the event and try to update it, they will get an ObjectIsStaleException because the update count of the in-memory object differs from that in the database.

Both of these methods provide signatures that support specifying an "in-place" refresh or restore. When "in-place" is true, then the Persistable argument passed to the method is populated with persistent attributes from the datastore. If false, then a new Persistable object is created and populated. The following are implications of using "in-place" refresh or restore.

• No additional memory is allocated for a new object.
• Other code that may contain in-memory references to the Persistable will "see" any changes made to the object after the "in-place" refresh or restore. In some cases, this may not be desirable. However, it can also be used in methods that need to persist changes to an object, but do not want to make references to that object stale.
• An object's non-peristent attributes state will be maintained after the refresh or restore. When a new object is created, the non-persistent or transient attributes are initialized to their default state.

Both of these methods provide signatures that support specifying a "locking" refresh or restore. When "lock" is true, then the persistent row in the datastore is locked. This means that no other code executing can modify, delete, or lock that same object without blocking.

Multiple Object Update and Delete

Objects in the persistent datastore can be updated or deleted without passing the full objects as arguments. A Batch Specfication object is constructed that describes the update or delete operation and the objects that are affected. This specfication object is then used as an argument to the PersistenceManagerSvr.execute(AbstractBatchSpec) method. Note that when using this method, no events are guaranteed to be dispatched. For more details on constructing a Batch Specification object, see the wt.fc.batch package.

Find

Objects in the persistent datastore can be retrieved without passing the full objects as arguments. A Statement Specfication object is constructed that describes the object types and criteria to use for querying the objects. This specfication object is then used as an argument to the PersistenceManager.find(StatementSpec) or PersistenceManagerSvr.query(StatementSpec) methods. For more details on constructing a Statement Specification object, see the wt.query package.

Objects retrieved from the persistent datastore are returned in a QueryResult object. When the PersistenceManager.find(StatementSpec) method is called, any objects retrieved that the user is not allowed to view are removed from the result before it is returned to the caller.

Navigate

A navigate operation is a specialized form of a retrival operation that returns objects associated to other objects. A navigate is similar to a "join" between the source object(s) and the associated objects. The Windchill information model supports associations of BinaryLink between two object types. Each side of the association has a named role. When navigating an association, the BinaryLink implementation type or linkClass is specified along with the role which specifies the direction to navigate. The navigate operations also support an "onlyOtherSide" argument. This argument indicates whether the association's link objects should be returned (onlyOtherSide=false) or the role objects should be returned (onlyOtherSide=true). The source object can either be a single Persistable object or a collection of Persistable objects. The navigate operation is supported with the helper method PersistenceHelper.navigate(Object,String,Class,boolean) which also returns a QueryResult object and filters out any objects that the user is not allowed to view.