jsdai.lang
Class SdaiTransaction

java.lang.Object
  extended byjsdai.lang.SdaiCommon
      extended byjsdai.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

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: 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.

Copyright © LKSoftWare GmbH, 1999-2008