Overview | Package | Class | Use | Tree | Deprecated | Index | Help
|  | BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

WebLogic Server 8.1 API Reference

## weblogic.transaction
Interface Transaction

public interface Transaction
extends javax.transaction.Transaction

This interface provides extensions to the javax.transaction.Transaction object for application or system use.

Transaction Properties

Transaction properties are key/value pairs. Once set, they remain associated with a transaction during its entire lifetime. They are propagated between machines as the transaction travels through the system. They also are saved in the transaction log, and restored during crash recovery processing.

If a transaction property is set more than once the latest value is retained. However, in some threaded and/or multi-server situations, this behavior may not be predictable.

Key names prefixed with "weblogic.transaction" are reserved for use by BEA Systems. Currently, there is one such property:

- `"weblogic.transaction.name"`: An application-specific identifier (String) associated with a transaction for administrative display, error logging, or tracing output.It has the same effect as calling `setName()`.

Transaction Status

Recovery and audit-trail procedures require more information about a transaction than the JTA Transaction interface furnishes; information such as the transaction identifier, the specific reason for a rollback, and any heuristic error messages. In addition, the time taken by the transaction and the amount of time left can be used as limits on certain operations.

Author:
  Copyright © 2004 BEA Systems, Inc. All Rights Reserved.
See Also:
  `Transaction`

Method Summary
`void` | `addProperties(java.util.Map props)` Adds a set of properties to a transaction by calling setProperty for all elements of props.
`boolean` | `enlistResource(NonXAResource nxar)` Enlist a Non-XA Resource in the transaction.
`java.lang.String` | `getHeuristicErrorMessage()` Returns the heuristic error message (if any) associated with the transaction.
`long` | `getMillisSinceBegin()` Returns the amount of time, in milliseconds, that the transaction has been in existence.
`java.lang.String` | `getName()` Retrieves the name previously associated with a transaction.
`java.util.Map` | `getProperties()` Gets all properties currently associated with a transaction.
`java.io.Serializable` | `getProperty(java.lang.String key)` Gets the value of a specific property.
`java.lang.Throwable` | `getRollbackReason()` Retrieves the rollback reason (if any) associated with the transaction.
`java.lang.String` | `getStatusAsString()` Returns the status of the transaction as a string.
`long` | `getTimeToLiveMillis()` Returns the amount of time, in milliseconds, that the transaction has left to go.
`javax.transaction.xa.Xid` | `getXid()`
`javax.transaction.xa.Xid` | `getXID()` Gets the transaction identifier.
`boolean` | `isTimedOut()` Returns true if the transaction has timed out, false otherwise.
`void` | `setName(java.lang.String n)` Associates a name with a transaction.
`void` | `setProperty(java.lang.String key, java.io.Serializable value)` Sets a property value to be associated with a transaction.
`void` | `setRollbackOnly(java.lang.String msg, java.lang.Throwable reason)` Wraps the rollback string message and the exception into a weblogic.utils.NestedException instance and calls setRollbackOnly with this new exception.
`void` | `setRollbackOnly(java.lang.Throwable reason)` Provides a reason for the rollback.

Methods inherited from interface javax.transaction.Transaction
`commit, delistResource, enlistResource, getStatus, registerSynchronization, rollback, setRollbackOnly`

Method Detail

### setName

    public void setName(java.lang.String n)

  Associates a name with a transaction. The name is typically used to describe a type of transaction and is not meant for describing each individual transaction. All internally generated error reports incorporate the name if present. Once set, the name cannot be changed.

### getName

    public java.lang.String getName()

  Retrieves the name previously associated with a transaction.

  Returns:
    Transaction name

### setProperty

    public void setProperty(java.lang.String key,
                            java.io.Serializable value)

  Sets a property value to be associated with a transaction.

  Parameters:
    `key` - A string key
    `value` - Property value, null means delete

### addProperties

    public void addProperties(java.util.Map props)

  Adds a set of properties to a transaction by calling setProperty for all elements of props.

  Parameters:
    `props` - Set of key/value pairs to add

### getProperty

    public java.io.Serializable getProperty(java.lang.String key)

  Gets the value of a specific property.

  Parameters:
    `key` - Property name
  Returns:
    Value of property or null if unset

### getProperties

    public java.util.Map getProperties()

  Gets all properties currently associated with a transaction.

  Returns:
    Map containing all key/value pairs

### setRollbackOnly

    public void setRollbackOnly(java.lang.Throwable reason)

  Provides a reason for the rollback. All rollbacks triggered inside the transaction service set the reason (timeouts, XA errors, unchecked exceptions in beforeCompletion, inability to contact the coordinator, etc.) Once set, the reason cannot be overwritten.

  Parameters:
    `reason` - the reason behind the rollback.

### setRollbackOnly

    public void setRollbackOnly(java.lang.String msg,
                                java.lang.Throwable reason)

  Wraps the rollback string message and the exception into a weblogic.utils.NestedException instance and calls setRollbackOnly with this new exception.

  Parameters:
    `reason` - the reason behind the rollback.
  See Also:
    `setRollbackOnly(Throwable)`

### getRollbackReason

    public java.lang.Throwable getRollbackReason()

  Retrieves the rollback reason (if any) associated with the transaction.

  Returns:
    the rollback reason (if any) associated with the transaction.
  See Also:
    `#setRollbackOnly(String msg)`

### getHeuristicErrorMessage

    public java.lang.String getHeuristicErrorMessage()

  Returns the heuristic error message (if any) associated with the transaction.

  Returns:

### getXID

    public javax.transaction.xa.Xid getXID()

  Gets the transaction identifier. It is important to know that the transaction adds some extra information to the Xid's gtrid and branch qualifier (bqual) when it calls a resource, so calls to tx.getXID().getGlobalTransactionId() before calling a resource (for the first time) and then subsequently differ in what is returned. There are two guarantees provided: 1. xid.equals() is not affected. An xid obtained from tx.getXID() and another obtained at a subsequent time are considered equal (for the same tx, of course). As mentioned earlier, this guarantee is not extended to the constituents of the xid, namely the gtrid and the bqual. 2. An XA resource will always be supplied the same xid (with the same gtrid and bqual) for a given transaction, in all its XAResource methods.

  Returns:
    Transaction identifier

### getXid

    public javax.transaction.xa.Xid getXid()

  See Also:
    `getXID()`

### getStatusAsString

    public java.lang.String getStatusAsString()

  Returns the status of the transaction as a string. The string contains the major state as specified in javax.transaction.Status, further embellished with a minor state (such as "logging", "pre-preparing", etc.)

  Returns:
    Transaction status in string form

### getMillisSinceBegin

    public long getMillisSinceBegin()

  Returns the amount of time, in milliseconds, that the transaction has been in existence. This value may not include network propagation time because there is no expectation of synchronized clocks.

  Returns:
    Existence time of transaction, in milliseconds

### getTimeToLiveMillis

    public long getTimeToLiveMillis()

  Returns the amount of time, in milliseconds, that the transaction has left to go. This time is meaningful only when the transaction is active, not when it is retrying commit or rollback.

  Returns:
    Time remaining for transaction, in milliseconds

### isTimedOut

    public boolean isTimedOut()

  Returns true if the transaction has timed out, false otherwise.

### enlistResource

    public boolean enlistResource(NonXAResource nxar)
                           throws javax.transaction.RollbackException,
                                  java.lang.IllegalStateException,
                                  javax.transaction.SystemException

  Enlist a Non-XA Resource in the transaction.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Documentation is available at http://e-docs.bea.com/wls/docs81
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD