jsdai.lang
Class SdaiTransaction

java.lang.Object
  jsdai.lang.SdaiCommon
      jsdai.lang.SdaiTransaction

public final class SdaiTransaction

extends jsdai.lang.SdaiCommon

Transactions control operations performed during the session. JSDAI conforms to transaction level 3, see "ISO 10303-22::13.1.1 Levels of transaction" for its definition. Therefore, an application always has to start either a read-only or read-write transaction before the contents of any SdaiModel is accessed. When a transaction is committed, the data which were changed are written to the binary files in the appropriate directories. In the case when a transaction is aborted, the previous state of all open SdaiRepositories with SdaiModels and their instances inside them is restored. Entity instances created after the most recent start transaction with read-write access or commit operation performed become invalid.
For details please look at "ISO 10303-22::7.4.5 sdai_transaction".

Remote database transactions

Last update 2006-01-25

Introduction

SdaiTransactions have some differences from SDAI transactions in ISO 10303-22 when used with remote JSDAI-DB repositories. The reason for this is multiuser user concurrent environment and underlying RDBMS specifics.

Transaction differences from SDAI

• Remote repository operations is part of SDAI transaction. This includes SdaiSession.createRepository(java.lang.String, java.lang.Object), SdaiSession.importClearTextEncoding(java.lang.String, java.lang.Object, java.lang.Object) SdaiRepository.openRepository(), and SdaiRepository.closeRepository(). This is related to the fact that all changes in RDBMS are transaction oriented. For backward compatibility if transaction is not running while the above methods are invoked the appropriate transaction is started and committed afterwards.
• Invoking SdaiTransaction methods commit() and abort() implies starting a new SDAI transaction associated with the same SdaiTransaction object. Also open remote repository contents are reloaded to reflect the status at the moment new transaction started. This includes aggregates of SdaiModels and SchemaInstances, associated models of SchemaInstances and entity instances and their values of SdaiModels that have their accesses started. JSDAI guarantees that SdaiModel, SchemaInstance and EEntity object instances are retained as long as they point to existing object on the database throughout the lifetime of active SdaiTransaction. Aggregate and ExternalData objects may become invalid after commit and abort operation.
• SdaiTransaction methods endTransactionAccessCommit() and endTransactionAccessAbort() end active transaction. Starting new SdaiTransaction afterwards does not ensure that open repositories reflect actual status on JSDAI-DB. However opening the repository with this new transaction following closing it will force refreshing the repository
• SdaiTransaction methods commit() and endTransactionAccessCommit() may fail if any of SdaiModels or SchemaInstances modified during the transaction was concurrently changed by another SdaiSession. If this situation occurs the commit operation fails with jsdai.client.SdaiExceptionRemote. Application can only abort transaction afterwards.
• Each of the models that have been modified since the last commit or abort operation is locked from changing within the commit and endTransactionAccessCommit operation for the moment changes are written to JSDAI-DB.

Concurrency support

The above mentioned remote SdaiTransaction specifics ensure data consistency even when many users are making changes on JSDAI-DB.

Bellow are the examples of some situations that may occur when several users are making simultaneous changes to JSDAI-DB:

Suppose there are two SdaiModels A and B. There are two users working on JSDAI-DB user1 and user2. Model A has entity instance #1 and model B has instances #2 and #3. Attribute #1.a1 has string value 'id1' and attribute #1.a2 has entity reference value #2.

1. timestamp01: user1 starts new transaction and starts R/W access for model A
   timestamp02: user2 starts new transaction and starts R/W access for model A
   timestamp03: user1 changes #1.a1 to 'id2'
   timestamp04: user2 changes #1.a1 to 'id2'
   timestamp05: user1 commits active transaction. Commit operation succeeds
   timestamp06: user2 commits active transaction. Commit operation fails
   timestamp07: user2 aborts active transaction
   timestamp08: user2 gets value of #1.a1 which is 'id2' now
   timestamp09: user2 changes #1.a1 to 'id3'
   timestamp10: user2 commits active transaction. Commit operation succeeds
   
   
2. timestamp01: user1 starts new transaction and starts R/W access for model A
   timestamp02: user2 starts new transaction and starts R/W access for model B
   timestamp03: user1 creates new instance #4 and assigns 'id2' to #4.a1
   timestamp04: user2 creates new instance #5 and assigns 'id2' to #5.a1
   timestamp05: user1 commits active transaction. Commit operation succeeds
   timestamp06: user2 commits active transaction. Commit operation fails
   timestamp07: user2 aborts active transaction
   timestamp08: user2 detects that #4 with #4.a1 value 'id2' was created
   timestamp09: user2 creates new instance #6 and assigns 'id3' to #6.a1
   timestamp10: user2 commits active transaction. Commit operation succeeds
   
   
3. timestamp01: user1 starts new transaction and starts access R/W for model A and R/O for model B
   timestamp02: user2 starts new transaction and starts access R/W for model B
   timestamp03: user1 changes #1.a2 to #3
   timestamp04: user2 deletes instance #3
   timestamp05: user1 commits active transaction. Commit operation succeeds
   timestamp06: user2 commits active transaction. Commit operation succeeds
   timestamp07: user1 aborts active transaction
   timestamp08: user1 detects that #1.a2 value is unset
   

Field Summary

static int	NO_ACCESS When getMode returns this value, all operations for accessing entity instances within session are disallowed.
static int	READ_ONLY When getMode returns this value, entity instances within session are or may become available (after starting access to owning model) for read-only access.
static int	READ_WRITE When getMode returns this value, entity instances within session are or may become available (after starting access to owning model) for read-write access.

Method Summary

void	abort() Restores the state of all open repositories, which existed at the time when the most recent start transaction with read-write access or commit operation was performed.
void	commit() Makes persistent all changes in all open repositories made since the most recent either start transaction with read-write access, commit, or abort operation was performed.
void	commit(java.lang.String appComment) Makes persistent all changes in all open repositories made since the most recent either start transaction with read-write access, commit, or abort operation was performed.
void	endTransactionAccessAbort() Ends the sequence of operations started by startTransactionReadWriteAccess or startTransactionReadOnlyAccess method.
void	endTransactionAccessCommit() Ends the sequence of operations started by startTransactionReadWriteAccess or startTransactionReadOnlyAccess method.
void	endTransactionAccessCommit(java.lang.String appComment) Ends the sequence of operations started by startTransactionReadWriteAccess or startTransactionReadOnlyAccess method.
int	getMode() Returns the current access mode provided by this SdaiTransaction within SdaiSession.
SdaiSession	getOwningSession() Returns the only one SdaiSession object.
java.lang.String	toString() Returns a description of this transaction as a String.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NO_ACCESS

public static final int NO_ACCESS

When getMode returns this value, all operations for accessing entity instances within session are disallowed.

See Also:

Constant Field Values

READ_ONLY

public static final int READ_ONLY

When getMode returns this value, entity instances within session are or may become available (after starting access to owning model) for read-only access.

See Also:

Constant Field Values

READ_WRITE

public static final int READ_WRITE

When getMode returns this value, entity instances within session are or may become available (after starting access to owning model) for read-write access.

See Also:

Constant Field Values

Method Detail

getMode

public int getMode()
            throws SdaiException

Returns the current access mode provided by this SdaiTransaction within SdaiSession. For data accessing, 3 modes are defined:

NO_ACCESS: the data cannot be accessed;

READ_ONLY: only read operations on the data are allowed;

READ_WRITE: read-write operations are allowed.

Returns:

the current access mode.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_NEXS, transaction does not exist.

getOwningSession

public SdaiSession getOwningSession()
                             throws SdaiException

Returns the only one SdaiSession object.

Returns:

the current session.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_NEXS, transaction does not exist.

commit

public void commit()
            throws SdaiException

Makes persistent all changes in all open repositories made since the most recent either start transaction with read-write access, commit, or abort operation was performed. The data of a repository to be stored persistently include:

• repository data outside its contents, such as name, description, author, organization, preprocessor version, language, context identifiers, and so on, if at least one such attribute was updated. This information is directed to the binary file named "header";
• general information about currently existing models and all information about schema instances provided at least one model or schema instance was created, deleted or modified during time interval considered by this method. These data are written down to binary file "contents"; this file also contains the largest number used to construct the persistent label for instances in the models of the repository;
• SdaiModels in which some data were modified and whose access mode is set. For each model, a separate binary file with the name of that model is created.

No function is performed if access mode for this transaction is read-only. The method does not change the current access mode.

This method also sets the change date for any model or schema instance that has been modified or created. Moreover, it sets the change date also for repository itself if some data in the repository was changed.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_NEXS, transaction does not exist.

SdaiException - TR_NAVL, transaction currently not available.

SdaiException - TR_EAB, transaction ended abnormally.

SdaiException - SY_ERR, underlying system error.

See Also:

abort(), SdaiModel.getChangeDate(), SchemaInstance.getChangeDate(), SdaiRepository.getChangeDate(), "ISO 10303-22::10.4.8 Commit", "ISO 10303-22::7.4.5 sdai_transaction"

commit

public void commit(java.lang.String appComment)
            throws SdaiException

Makes persistent all changes in all open repositories made since the most recent either start transaction with read-write access, commit, or abort operation was performed. This is an extension of SDAI.

Parameters:

appComment - application provided comment to be recorded in JSDAI-DB for history tracking. Application comment is ignored if JSDAI-DB changes did not occur for the current transaction or if JSDAI-DB does not support recording commit operations

Throws:

SdaiException - if an error occurs during the operation or in underlying JSDAI operations

Since:

4.1.0

See Also:

commit()

abort

public void abort()
           throws SdaiException

Restores the state of all open repositories, which existed at the time when the most recent start transaction with read-write access or commit operation was performed. All deleted models, schema instances and entity instances are restored, all created models, schema instances and entity instances no longer exist, and all modifications to models including instances within them, to schema instances and to repository attributes outside its contents are lost. Deleted repositories, however, are not restored, and created repositories survive during this operation.

No function is performed if access mode for this transaction is read-only. The method does not change the current access mode.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_NEXS, transaction does not exist.

SdaiException - TR_NAVL, transaction currently not available.

SdaiException - TR_EAB, transaction ended abnormally.

SdaiException - SY_ERR, underlying system error.

See Also:

commit(), "ISO 10303-22::10.4.9 Abort", "ISO 10303-22::7.4.5 sdai_transaction"

endTransactionAccessCommit

public void endTransactionAccessCommit()
                                throws SdaiException

Ends the sequence of operations started by startTransactionReadWriteAccess or startTransactionReadOnlyAccess method. Before ending the transaction access the commit operation is performed. Further access to entity instances within the session is available only after the next invocation of either startTransactionReadWriteAccess or startTransactionReadOnlyAccess method.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_NEXS, transaction does not exist.

SdaiException - TR_NAVL, transaction currently not available.

SdaiException - TR_EAB, transaction ended abnormally.

SdaiException - SY_ERR, underlying system error.

See Also:

commit(), SdaiSession.startTransactionReadWriteAccess(), SdaiSession.startTransactionReadOnlyAccess(), "ISO 10303-22::10.4.10 End transaction access and commit", "ISO 10303-22::7.4.5 sdai_transaction"

endTransactionAccessCommit

public void endTransactionAccessCommit(java.lang.String appComment)
                                throws SdaiException

Ends the sequence of operations started by startTransactionReadWriteAccess or startTransactionReadOnlyAccess method. This is an extension of SDAI.

Parameters:

appComment - application provided comment to be recorded in JSDAI-DB for history tracking. Application comment is ignored if JSDAI-DB changes did not occur for the current transaction or if JSDAI-DB does not support recording commit operations

Throws:

SdaiException - if an error occurs during the operation or in underlying JSDAI operations

Since:

4.1.0

See Also:

endTransactionAccessCommit()

endTransactionAccessAbort

public void endTransactionAccessAbort()
                               throws SdaiException

Ends the sequence of operations started by startTransactionReadWriteAccess or startTransactionReadOnlyAccess method. Before ending the transaction access the abort operation is performed. Further access to entity instances within the session is available only after the next invocation of either startTransactionReadWriteAccess or startTransactionReadOnlyAccess method.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_NEXS, transaction does not exist.

SdaiException - TR_NAVL, transaction currently not available.

SdaiException - TR_EAB, transaction ended abnormally.

SdaiException - SY_ERR, underlying system error.

See Also:

abort(), SdaiSession.startTransactionReadWriteAccess(), SdaiSession.startTransactionReadOnlyAccess(), "ISO 10303-22::10.4.11 End transaction access and abort", "ISO 10303-22::7.4.5 sdai_transaction"

toString

public java.lang.String toString()

Returns a description of this transaction as a String. It includes constant string "SdaiTransaction mode: " and the access mode provided by this transaction.

Returns:

a description of the transaction.