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.
DatastoreArray	This interface provides an abstraction for a Datastore array.
DatastoreSequence	This interface provides an abstraction for a Datastore sequence.
DatastoreStruct	This interface provides an abstraction for a Datastore sequence.
Evolvable	Deprecated. Use wt.util.Evolvable
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.
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.
ResultProcessor	This interface specifies methods needed to process results directly from the low level persistence layer.
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

DynamicEnumType	Supported API: true Extendable: true
EnumeratedType	A type that has a defined list of valid values, which may change over time.
EnumeratedTypeUtil	A set utility methods for working with EnumeratedTypes.
ForeignKeyLink	Abstract class that represents an association between two Persistables where one of the objects persistently holds a reference to the other.
IconDelegate	Retrieves icons for Windchill objects.
IconDelegateFactory	A factory for icon delegates.
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.
IdentityServiceEvent	The IdentityServiceEvent encapsulates identity change events.
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.
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.
ObjectToObjectLink	Abstract class that represents an association between two Persistable objects.
PagingQueryResult	This class is a container of results returned from a query along with paging session information.
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.
PersistenceServerHelper	This class implements helper methods for server side PersistenceManagerSvr operations.
QueryResult	The QueryResult class is a container of results returned from a query.
ReferenceFactory	A factory for getting references and strings that refer to persistable objects.
ResultProcessorAdapter	This abstract class can be extended to provide a custom ResultProcessor that processes results directly from the low level persistence layer.
SemanticKey	The SemanticKey class helps to ensure the uniqueness constraint on object's identity.
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.
StreamObjectVector	Supported API: true Extendable: false
WTObject	WTObject is the abstract base class for all domain-specific item and link classes.

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 StatementSpec 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 StatementSpec 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. In addition, objects can be returned directly to a custom ResultProcessor that extends ResultProcessorAdapter. using the PersistenceManager.find(StatementSpec,ResultProcessor) or PersistenceManagerSvr.query(StatementSpec,ResultProcessor) methods.

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.