com.ptc.windchill.esi.txn
Class ESITransactionUtility

java.lang.Object
  com.ptc.windchill.esi.txn.ESITransactionUtility

All Implemented Interfaces:

Externalizable, Serializable

public final class ESITransactionUtility
extends Object
implements Externalizable

Provides common services which are not intended to be available to remote consumers. This class is not thread-safe. A separate instance must be created if multiple threads are to use the services of the class.

Supported API: true

Extendable: false

See Also:

Serialized Form

Method Summary

void	abortTransaction(Persistable obj) Remove a transaction.
void	addTransactionMessage(ESITransaction txn, String text, boolean txnRequired) Adds a message to an ESITransaction.
void	adjustTargetAssignments(String ufids, com.infoengine.object.factory.Group targetInfo) Given a concatenated set of UFIDs (for WTParts) and a Collection of ESITarget UFIDs, make (or remove) any required assignments.
void	createReleaseActivity(Persistable persistable, String description, ESITransaction transaction, boolean successful, ESITarget target, String message, String timestamp, String action, String cls, String user) Create and save a new ReleaseActivity from the arguments Supported API: true
ESITransaction	createTransaction(Persistable object) Creates a new ESITransaction that is associated to the argument.
ESITransaction	createTransaction(Persistable object, String userName) Creates a new ESITransaction that is associated to the argument.
void	deleteTargetAssociation(ESITargetAssignmentLink link) Removes the argument from the database.
void	deleteTargetAssociation(com.infoengine.object.factory.Group links) Deletes from the database the ESITargetAssignmentLink objects that are identified by the argument.
QueryResult	findTransactions(Persistable obj) Returns all ESITransactions for the given object.
QueryResult	findTransactions(Persistable obj, String status) Returns ESITransactions for the given object and status.
Collection	getActivities(ESITransaction txn, String targetID) Returns the ReleaseActivities associated with the ESITransaction and the Distribution Target in the argument.
Collection	getActivities(Persistable object) This method will return a Collection of ReleaseActivities that are associated with the persisable object.
Collection	getActivities(String ufid) Returns the ReleaseActivities associated with the ESITransaction identified by the UFID in the argument.
Collection	getAllActivities(Persistable object) This method will return a Collection of ReleaseActivities that are associated with the persisable object.
Collection	getBOMActivities(Collection parts) Given a collection of parts returns a collection of ReleaseActivity objects where the release activity represents a BOM, for any iterations of the part's part master.
Eff[]	getLatestExportedEffs(EffManagedVersion part, ESITarget target) Fetches the date, serial number and lot number effectivities associated with the given part that were last exported to the given target, stores them in an array of Eff instances and returns the array to the caller.
Collection	getLatestUnreleasedDocuments(Collection docs, Collection targets) Given a collection of WTDocuments and targets this method returns a collection of ESITargetAssocations for documents that have not been exported to that target.
com.infoengine.object.factory.Group	getReleaseActivities(String ufid) Returns an Info*Engine Group of mapped ReleaseActivity objects given the ufid of the ESITransaction object.
com.infoengine.object.factory.Group	getReleaseActivitiesMessage(String ufid) Returns an Info*Engine Group of mapped ReleaseActivityMessage object given the ufid of the ReleaseActivity object.
com.infoengine.object.factory.Group	getTargetsWithHistory(Collection objects) Returns an Info*Engine Group of mapped ESITargetHistory objects.
Collection	getTargetsWithHistory(Persistable object) Returns a Collection of ESITargetHistory objects.
ESITransaction	getTransaction(String number) Return the ESITransaction object whose number matches the method argument.
Collection	getTransactionActivities(String id) Return a collection ReleaseActivities associated with the ESITransaction identified by the argument.
com.infoengine.object.factory.Group	getTransactionLogMessage(String ufid) Returns an Info*Engine Group of mapped ESITransactionMessage object given the ufid of the ESITransaction object.
com.infoengine.object.factory.Group	getTransactions(com.infoengine.object.factory.Group ufids) Returns an Info*Engine Group of ESITransaction objects that are associated with the objects in the argument.
boolean	hasReleased(Persistable obj, ESITarget target) Check if the object has been released successfully for the given target.
boolean	hasTxFailed(Persistable obj) Returns true if find a related transaction failed for a given object, otherwise return false.
boolean	hasTxSucceed(Persistable obj) Returns true if find a transaction is SUCCEED for the given object, otherwise returns false.
void	hideTransaction(String ufid) Hide an ESITransaction from the user interface.
boolean	isInRelease(Persistable obj) This is to check if the releasable object is in ESI release .
boolean	isPartNewerThan(WTPart current, WTPart other) This method checks two different part versions and returns true if the current iteration is newer than the other version.
boolean	isPartReleaseNeeded(Collection assns) Given a collection of ESITargetAssociations, returns true if any of the persistable objects have not been published to the ESI target identified in the target association.
boolean	isTxnPending(Persistable object) Determines whether a transaction containing the argument is already active.
boolean	isTxPending(Persistable obj) Returns true if ESI transaction for the given object is in pending status, otherwise return false.
boolean	isTxProcessing(Persistable obj) Returns true if the ESI transaction is in processing for the given object, otherwise return false.
Collection	latestPartExport(Collection parts) Returns a collection of ESITargetAssociations Supported API: true
static void	performStartupProcess() Performs the necessary startup logic for the Transaction Utility.
void	postEvent(String objectID, String transaction, boolean isSuccessful, String message) Process postEvent RPC requests Supported API: true
void	postResult(String objectID, String description, String txnID, boolean isSuccessful, boolean isSubtran, String targetSystem, String message, String timestamp, String action, String cls, String user) Process postResult RPC requests Supported API: true
void	recordExport(Persistable obj, ESITarget org, String releaseClass) Mark a persistable as exported to an organization Supported API: true
void	removePending(ESITransaction txn) Deletes all ReleaseActivities that have a status of PENDING and are associated with the argument. The method does not create a database transaction.
void	removeTransactionMessage(ESITransaction txn) Removes any ESITransactionMessage that is associated with an ESITransaction.
void	updateTransaction(ESITransaction txn) Save a transaction in the database Supported API: true
void	validateDelete(WTPart part) Deprecated at X05/R8.0, replaced by by calling isInRelease and referential integrity exception delegate.

Methods inherited from class java.lang.Object

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

Method Detail

abortTransaction

public final void abortTransaction(Persistable obj)

Remove a transaction.

Note : This method can ONLY be called on ESI workflow if any system errors (e.g. JMS server not available ) occured during release, means that unable to send messages to com.ptc.windchill.esi.Event queue.

Supported API: true

Parameters:

obj -

addTransactionMessage

public final void addTransactionMessage(ESITransaction txn,
                                        String text,
                                        boolean txnRequired)
                                 throws WTException

Adds a message to an ESITransaction. If the transaction already had a message, the old one is replaced by the new message. This results in multiple database activities which should be wrapped in a database transaction. If caller has started a transaction, pass false in the txnRequired argument, otherwise pass true in the argument.

Supported API: true

Parameters:

txn - The transaction to which an message is to be added.

text - The text of the message to add.

txnRequired - Should this request be wrapped in a database transaction. Should be false if caller has started a transaction.

Throws:

WTException

adjustTargetAssignments

public final void adjustTargetAssignments(String ufids,
                                          com.infoengine.object.factory.Group targetInfo)
                                   throws WTException

Given a concatenated set of UFIDs (for WTParts) and a Collection of ESITarget UFIDs, make (or remove) any required assignments.

• The ufids argument contains a set of UFIDs which define the parts to operate on.
• The targetInfo argument is an Group. Each element in the group has Atts that:
1. define the ufid of an ESITarget
2. define the operation to perfom on the parts. If the operation is add, then all parts that do not have the target assigned are given the assignment. If the operation is remove, then all existing assignments for that target to any of the existing parts are removed. However, an exception is thrown if any of the assignments have already been published

Once this method determines that there are no deletion requests for already-published targets, all work is delegated to an instance of ESITargetUtilty.

Supported API: true

Parameters:

ufids - A concatenated list of UFIDs of the objects to operate on.

targetInfo - A collection of Info*Engine elements containing the UFIDs of the ESITargets to assign/remove and the operation to perform.

Throws:

WTException

createReleaseActivity

public final void createReleaseActivity(Persistable persistable,
                                        String description,
                                        ESITransaction transaction,
                                        boolean successful,
                                        ESITarget target,
                                        String message,
                                        String timestamp,
                                        String action,
                                        String cls,
                                        String user)
                                 throws WTException

Create and save a new ReleaseActivity from the arguments

Supported API: true

Parameters:

persistable - The object being flagged as released

description - A textual description of the release type

transaction - The transaction associated with this activity.

successful - Was the transaction successful?

target - The destination where this object was released

message - An optional message to associate with the ReleaseActivity

timestamp - The time when the ReleaseActivity occurred. Must resolve to a java.sql.TimeStamp. If it doesn't the current time will be used.

action - must be "create", "change", or "delete" (case insensitive)

cls - The ESI logical class of the object being flagged

user - The user who requested the activity

Throws:

WTException

createTransaction

public final ESITransaction createTransaction(Persistable object)
                                       throws WTException

Creates a new ESITransaction that is associated to the argument. Persists the transaction and the relationship.

Supported API: true

Parameters:

object - The object that is to be associated with the ESITransaction.

Returns:

ESITransaction

Throws:

WTException

createTransaction

public final ESITransaction createTransaction(Persistable object,
                                              String userName)
                                       throws WTException

Creates a new ESITransaction that is associated to the argument. Persists the transaction and the relationship.

Supported API: true

Parameters:

object - The object that is to be associated with the ESITransaction.

userName - The name of the user responsible for initiating the transaction.

Returns:

ESITransaction

Throws:

WTException

deleteTargetAssociation

public final void deleteTargetAssociation(ESITargetAssignmentLink link)
                                   throws WTException

Removes the argument from the database. Ensures that the target has not already been published before allowing the deletion to occur.

Supported API: true

Parameters:

link - The ESITargetAssignmentLink that is to be deleted.

Throws:

WTException

deleteTargetAssociation

public final void deleteTargetAssociation(com.infoengine.object.factory.Group links)
                                   throws WTException

Deletes from the database the ESITargetAssignmentLink objects that are identified by the argument. Delegates all work to an instance of ESITransactionUtility. Uses a database transaction so that all objects are deleted or none of them are.

Supported API: true

Parameters:

links - An Info*Engine group of Element objects. Each element has an Att object that contains the UFID of an ESITargetAssignmentLink that is to be deleted.

Throws:

WTException

findTransactions

public final QueryResult findTransactions(Persistable obj)
                                   throws com.ptc.windchill.esi.utl.ESIException

Returns all ESITransactions for the given object.

Supported API: true

Parameters:

obj -

Returns:

QueryResult

Throws:

com.ptc.windchill.esi.utl.ESIException

findTransactions

public final QueryResult findTransactions(Persistable obj,
                                          String status)
                                   throws com.ptc.windchill.esi.utl.ESIException

Returns ESITransactions for the given object and status.

Supported API: true

Parameters:

obj -

status -

Returns:

QueryResult

Throws:

com.ptc.windchill.esi.utl.ESIException

getActivities

public final Collection getActivities(String ufid)
                               throws WTException

Returns the ReleaseActivities associated with the ESITransaction identified by the UFID in the argument.

Supported API: true

Parameters:

ufid - The UFID of an ESITransaction.

Returns:

Collection

Throws:

WTException

getActivities

public final Collection getActivities(Persistable object)
                               throws WTException

This method will return a Collection of ReleaseActivities that are associated with the persisable object. Only release activities that are Pending or Successful are returned.

Supported API: true

Parameters:

object - Persistable object whose history is to be retrieved.

Returns:

Collection

Throws:

WTException

getAllActivities

public final Collection getAllActivities(Persistable object)
                                  throws WTException

This method will return a Collection of ReleaseActivities that are associated with the persisable object.

Supported API: true

Parameters:

object - Persistable object whose history is to be retrieved.

Returns:

Collection

Throws:

WTException

getBOMActivities

public final Collection getBOMActivities(Collection parts)
                                  throws WTException

Given a collection of parts returns a collection of ReleaseActivity objects where the release activity represents a BOM, for any iterations of the part's part master. Find the part master associated with the part in the argument. Find all iterations of the master. If any of those iterations has a successful ReleaseActivity that has a releaseClass indicating it is a BOM, add it to the result.

Supported API: true

Parameters:

parts - A collection of WTPart instances to examine.

Returns:

Collection

Throws:

WTException

getLatestUnreleasedDocuments

public final Collection getLatestUnreleasedDocuments(Collection docs,
                                                     Collection targets)
                                              throws WTException

Given a collection of WTDocuments and targets this method returns a collection of ESITargetAssocations for documents that have not been exported to that target. The returned target association persistable objects are the highest version.iteration associated with an ESITarget. In other words, it is the last object that was released to the target. The objects in the request class must all be members of the same class.

Supported API: true

Parameters:

docs - This is a collection of WTDocuments. The persistables must all be objects of the same class.

targets - Collection of ESITargets associated with the documents.

Returns:

Collection

Throws:

WTException

getReleaseActivities

public final com.infoengine.object.factory.Group getReleaseActivities(String ufid)
                                                               throws WTException

Returns an Info*Engine Group of mapped ReleaseActivity objects given the ufid of the ESITransaction object.

Supported API: true

Parameters:

ufid - The ufid of the ESITransaction object.

Returns:

Group

Throws:

WTException

getReleaseActivitiesMessage

public final com.infoengine.object.factory.Group getReleaseActivitiesMessage(String ufid)
                                                                      throws WTException

Returns an Info*Engine Group of mapped ReleaseActivityMessage object given the ufid of the ReleaseActivity object.

Supported API: true

Parameters:

ufid - ufid of the ReleaseActivity object.

Returns:

Group

Throws:

WTException

getTargetsWithHistory

public final com.infoengine.object.factory.Group getTargetsWithHistory(Collection objects)
                                                                throws WTException

Returns an Info*Engine Group of mapped ESITargetHistory objects. The ESITargetHistory objects contain the following

• The target attribute of the will be one of the available targets.
• The persistableObject will be one of the objects in the argument to this method.
• If the persistable object has been exported to the target, the releaseAttribute will contain the appropriate ReleaseActivity.

The result will be serialized by the ESI mapping service to a group of Info*Engine Element objects.

Supported API: true

Parameters:

objects - A collection of persistable objects. The objects must all be instances of the same class.

Returns:

Group

Throws:

WTException

getTargetsWithHistory

public final Collection getTargetsWithHistory(Persistable object)
                                       throws WTException

Returns a Collection of ESITargetHistory objects. The ESITargetHistory objects contain the following

• The target attribute of the will be one of the available targets.
• The persistableObject will be one of the objects in the argument to this method.
• If the persistable object has been exported to the target, the releaseAttribute will contain the appropriate ReleaseActivity.

Supported API: true

Parameters:

object - The Persistable whose target assignments are to be queried.

Returns:

Collection

Throws:

WTException

getTransaction

public final ESITransaction getTransaction(String number)
                                    throws WTException

Return the ESITransaction object whose number matches the method argument. Throw an ESIException if no entry is found.

Supported API: true

Parameters:

number - The transaction number of the desired ESITransaction object.

Returns:

ESITransaction

Throws:

WTException

getTransactions

public final com.infoengine.object.factory.Group getTransactions(com.infoengine.object.factory.Group ufids)
                                                          throws WTException

Returns an Info*Engine Group of ESITransaction objects that are associated with the objects in the argument. The argument is an Info*Engine Group containing Elements that have been created by (or resemble the output of) a Query-Objects webject.

Supported API: true

Parameters:

ufids - An Info*Engine Group containing Elements that have been create by (or resemble the output of) a Query-Objects webject.

Returns:

Group

Throws:

WTException

getTransactionActivities

public final Collection getTransactionActivities(String id)
                                          throws WTException

Return a collection ReleaseActivities associated with the ESITransaction identified by the argument. If no such transaction, throw an ESIException.

Supported API: true

Parameters:

id - the id of the transaction of interest.

Returns:

Collection

Throws:

WTException

getTransactionLogMessage

public final com.infoengine.object.factory.Group getTransactionLogMessage(String ufid)
                                                                   throws WTException

Returns an Info*Engine Group of mapped ESITransactionMessage object given the ufid of the ESITransaction object.

Supported API: true

Parameters:

ufid - ufid of the ESITransaction object.

Returns:

Group

Throws:

WTException

hasReleased

public final boolean hasReleased(Persistable obj,
                                 ESITarget target)
                          throws com.ptc.windchill.esi.utl.ESIException

Check if the object has been released successfully for the given target.

Supported API: true

Parameters:

obj -

target -

Returns:

boolean

Throws:

com.ptc.windchill.esi.utl.ESIException

hasTxFailed

public final boolean hasTxFailed(Persistable obj)
                          throws com.ptc.windchill.esi.utl.ESIException

Returns true if find a related transaction failed for a given object, otherwise return false.

Supported API: true

Parameters:

obj -

Returns:

boolean

Throws:

com.ptc.windchill.esi.utl.ESIException

hasTxSucceed

public final boolean hasTxSucceed(Persistable obj)
                           throws com.ptc.windchill.esi.utl.ESIException

Returns true if find a transaction is SUCCEED for the given object, otherwise returns false.

Supported API: true

Parameters:

obj -

Returns:

boolean

Throws:

com.ptc.windchill.esi.utl.ESIException

hideTransaction

public final void hideTransaction(String ufid)
                           throws WTException

Hide an ESITransaction from the user interface.

Supported API: true

Parameters:

ufid -

Throws:

WTException

isInRelease

public boolean isInRelease(Persistable obj)
                    throws com.ptc.windchill.esi.utl.ESIException

This is to check if the releasable object is in ESI release . Returns true if the transaction or release activity has been created for the given releasable object or any releasable iteration for the given master, regarding less the targets and the status. Otherwise returns false.

Supported API: true

Parameters:

obj - The persistable object.

Returns:

boolean

Throws:

com.ptc.windchill.esi.utl.ESIException

isPartNewerThan

public final boolean isPartNewerThan(WTPart current,
                                     WTPart other)

This method checks two different part versions and returns true if the current iteration is newer than the other version. if the esi property enableCheckForPartIteration is set to true then part iterations are also checked.

Supported API: true

Parameters:

current - current part iteration to test

other - previous part iteration.

Returns:

boolean

isPartReleaseNeeded

public final boolean isPartReleaseNeeded(Collection assns)
                                  throws WTException

Given a collection of ESITargetAssociations, returns true if any of the persistable objects have not been published to the ESI target identified in the target association.

Supported API: true

Parameters:

assns - A Collection of ESITargetAssociations.

Returns:

boolean

Throws:

WTException

isTxPending

public final boolean isTxPending(Persistable obj)
                          throws com.ptc.windchill.esi.utl.ESIException

Returns true if ESI transaction for the given object is in pending status, otherwise return false.

Supported API: true

Parameters:

obj -

Returns:

boolean

Throws:

com.ptc.windchill.esi.utl.ESIException

isTxnPending

public final boolean isTxnPending(Persistable object)
                           throws WTException

Determines whether a transaction containing the argument is already active. Will return true if the object is associated to a transaction whose status is PROCESSING or PENDING.

Supported API: true

Parameters:

object - The object of interest

Returns:

boolean

Throws:

WTException

isTxProcessing

public final boolean isTxProcessing(Persistable obj)
                             throws com.ptc.windchill.esi.utl.ESIException

Returns true if the ESI transaction is in processing for the given object, otherwise return false.

Supported API: true

Parameters:

obj -

Returns:

boolean

Throws:

com.ptc.windchill.esi.utl.ESIException

latestPartExport

public final Collection latestPartExport(Collection parts)
                                  throws WTException

Returns a collection of ESITargetAssociations

Supported API: true

Parameters:

parts - A collection of ESITargetAssociations with WTParts as the pesistable object.

Returns:

Collection

Throws:

WTException

performStartupProcess

public static void performStartupProcess()
                                  throws WTException

Performs the necessary startup logic for the Transaction Utility. Should be called upon method server startup.

Supported API: true

Throws:

WTException

postEvent

public final void postEvent(String objectID,
                            String transaction,
                            boolean isSuccessful,
                            String message)
                     throws WTException

Process postEvent RPC requests

Supported API: true

Parameters:

objectID - The object which is associated with the Windchill event that this RPC will create. It is expected to be the value supplied in the that is provided in the ESIEvent that intiates the transaction.

transaction - The transaction number that is associated with this event

isSuccessful - Did the request succeed?

message - An optional message to pass to the Windchill workflow that is suspended and waiting for this event.

Throws:

WTException

postResult

public final void postResult(String objectID,
                             String description,
                             String txnID,
                             boolean isSuccessful,
                             boolean isSubtran,
                             String targetSystem,
                             String message,
                             String timestamp,
                             String action,
                             String cls,
                             String user)
                      throws WTException

Process postResult RPC requests

Supported API: true

Parameters:

objectID - The UFID of the object being tracked

description - A user-friendly description of the object

txnID - The transaction number related to this request

isSuccessful - Did the request succeed?

isSubtran - If false, this is the end of the transaction messages. If true, it is a transaction line item.

targetSystem - The ESITarget system id associated with this request.

message - An optional textual description. Generally used for error messages, but not restricted to errors.

timestamp - Optional parameter. If supplied must be a string that can be converted to a java.sql.timestamp.

action - The action that was requested. Must be one of the values defined by ReleaseActivityAction.

cls - The ESI logical class of the object being tracked. This value came from the ESI RPC response that generated the ESI transaction.

user - The user who requested the transaction.

Throws:

WTException

recordExport

public final void recordExport(Persistable obj,
                               ESITarget org,
                               String releaseClass)
                        throws WTException

Mark a persistable as exported to an organization

Supported API: true

Parameters:

obj - the object being flagged

org - The ESIOrganization which received the object

releaseClass - the type of release activity.

Throws:

WTException

removePending

public final void removePending(ESITransaction txn)
                         throws WTException

Deletes all ReleaseActivities that have a status of PENDING and are associated with the argument.
The method does not create a database transaction. It is assumed that this operation will be performed as part of a larger database request.

Supported API: true

Parameters:

txn - The ESITranaction that has completed.

Throws:

WTException

removeTransactionMessage

public final void removeTransactionMessage(ESITransaction txn)
                                    throws WTException

Removes any ESITransactionMessage that is associated with an ESITransaction.

Supported API: true

Parameters:

txn - The transaction from which all messages are to be removed.

Throws:

WTException

updateTransaction

public final void updateTransaction(ESITransaction txn)
                             throws WTException

Save a transaction in the database

Supported API: true

Parameters:

txn - The transaction to be saved

Throws:

WTException

validateDelete

public final void validateDelete(WTPart part)
                          throws WTException

Deprecated at X05/R8.0, replaced by by calling isInRelease and referential integrity exception delegate. Throws an exception if the argument is not eligible to be deleted.

1. Examines ESI properties to determine whether or not to check ReleaseActivity objects. If the check is to be made, the method throws a WTException if the argument is associated to one or more ReleaseActivity (or ESIProperties-designated subclass) objects.
2. Examines ESI properties to determine whether or not to check ESITransactionObjectLink objects. If the check is to be made, the method throws a WTException of the argument is associated to one or more ESITransactionObjectLink (or ESIProperties-designated subclass) objects.

Supported API: true

Parameters:

part - The part to evaluate.

Throws:

WTException

getActivities

public final Collection getActivities(ESITransaction txn,
                                      String targetID)
                               throws WTException

Returns the ReleaseActivities associated with the ESITransaction and the Distribution Target in the argument.

Supported API: true

Parameters:

txn - An ESITransaction object.

targetID - The System of an ESITrarget

Returns:

Collection

Throws:

WTException

getLatestExportedEffs

public Eff[] getLatestExportedEffs(EffManagedVersion part,
                                   ESITarget target)
                            throws WTException

Fetches the date, serial number and lot number effectivities associated with the given part that were last exported to the given target, stores them in an array of Eff instances and returns the array to the caller. Some of the elements in the output array could be null, depending on whether or not the given type of effectivity was exported to the target for the part.

Supported API: true

Parameters:

part - WTPart instance for which to fetch the last exported date, serial number and lot number effectivities

target - ESITarget instance for which to fetch the last exported date, serial number and lot number effectivities

Returns:

Eff[] array of Eff objects that represent the last exported date, serial number and lot number effectivities

Throws:

wt.util.WTException, - if thrown from latestEffExport()

WTException