net.m2technologies.open_arm.transaction
Class ArmTransactionImpl

java.lang.Object
  net.m2technologies.open_arm.transaction.ArmInterfaceImpl
      net.m2technologies.open_arm.transaction.UniqueObjectImpl
          net.m2technologies.open_arm.transaction.ArmTransactionImpl

All Implemented Interfaces:

ArmInterface, ArmTransaction, TransactionState, UniqueObject

Direct Known Subclasses:

ArmTransactionWithMetricsImpl

public class ArmTransactionImpl

extends UniqueObjectImpl

implements ArmTransaction, TransactionState

Copyright 2005 Mark Masterson

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Version:

0.009

Author:

Mark Masterson

Field Summary

Fields inherited from class net.m2technologies.open_arm.transaction.ArmInterfaceImpl

HASH_CODE_MAGIC_NUMBER

Constructor Summary

ArmTransactionImpl(ArmTransactionFactory creatingFactory, ArmTransactionDefinition transactionDefiniton, ArmApplication app, java.lang.String[] contextValues)

Method Summary

int	bindThread() Deprecated. because C programmers don't like OO
long	blocked() Use this method to notify OpenArm that your transaction has reached a point where it will have to wait, synchronously, for some external resource.
boolean	equals(java.lang.Object o)
ArmApplication	getApplication() Each transaction gets initialized with an instance of the ArmApplication within whose context the transaction is running.
long	getArrivalTime()
long	getBlockingHandle()
java.lang.String	getContextURIValue()
java.lang.String	getContextValue(int index)
ArmCorrelator	getCorrelator() You should only call this method within a transactional scope -- that means you should always call start() first, before you call this method.
ArmTransactionDefinition	getDefinition() Each transaction gets initialized with an instance of the ArmTransactionDefinition that represents the type of the transaction.
ArmID	getId()
ArmCorrelator	getParentCorrelator() If there was a parent correlator at instantiation, you get it back with this method.
long	getStartTime()
int	getStatus() The stop(int) method requires an int parameter that represents the completion status of the transaction.
boolean	getTraceState()
ArmUser	getUser()
int	hashCode()
boolean	isTraceRequested()
int	reset() Calling this will reset all of the counters being maintained within a transactional scope. These include: -- start time -- arrival time -- trace state -- the parent correlator
int	setArrivalTime() Used to set the arrival time of the transactional scope. Let's say you've got a transaction with a somewhat complex phase structure, and you have some sort of setup that happens immediately after the transaction starts, but before the point where you think the real action gets going.
void	setArrivalTime(long arrivalTime)
int	setContextURIValue(java.lang.String value)
int	setContextValue(int index, java.lang.String value)
void	setParentCorrelator(ArmCorrelator parentCorrelator)
void	setStartTime(long startTime)
int	setTraceRequested(boolean traceState)
void	setTraceState(boolean traceState)
int	setUser(ArmUser user)
int	start() Used to start the clock for this transactional scope.
int	start(ArmCorrelator parentCorr) Used to start the clock for this transactional scope.
int	start(byte[] parentCorr) Used to start the clock for this transactional scope.
int	start(byte[] parentCorr, int offset) Deprecated. because C programmers don't like OO
int	stop(int status) Used to stop the clock for this transactional scope.
int	stop(int status, java.lang.String diagnosticDetail) Used to stop the clock for this transactional scope.
int	unbindThread() Deprecated. because C programmers don't like OO
int	unblocked(long blockHandle) Use this method to notify OpenArm that your transaction has stopped waiting synchronously, for some external resource.
int	update() Use this method to notify OpenArm that your transaction is still out there and alive.

Methods inherited from class net.m2technologies.open_arm.transaction.UniqueObjectImpl

getID, getName

Methods inherited from class net.m2technologies.open_arm.transaction.ArmInterfaceImpl

getCreatingFactory, getErrorCode, getErrorMessage, setErrorCode, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.opengroup.arm40.transaction.ArmInterface

getErrorCode, getErrorMessage, setErrorCode

Methods inherited from interface net.m2technologies.open_arm.transaction.UniqueObject

getID, getName

Constructor Detail

ArmTransactionImpl

public ArmTransactionImpl(ArmTransactionFactory creatingFactory,
                          ArmTransactionDefinition transactionDefiniton,
                          ArmApplication app,
                          java.lang.String[] contextValues)

Method Detail

bindThread

public int bindThread()

Deprecated. because C programmers don't like OO

This method is currently disabled in our implementation, becuase we haven't understood it yet, or found a way to translate it into a sensible Java implementation. Calling it will provoke a RuntimeException.

Specified by:

bindThread in interface ArmTransaction

Returns:

RuntimeException

blocked

public long blocked()

Use this method to notify OpenArm that your transaction has reached a point where it will have to wait, synchronously, for some external resource. Old timers refer to this as "blocking" rather than write out "waitingForExternalResource", which takes too many bytes... :-)

Specified by:

blocked in interface ArmTransaction

Returns:

a "block handle" -- more old timer stuff. It's just a number, and it gets incremented each time somebody calls this method. You use it as the parameter to unblocked(long), and if we were C programmers, it might have some meaning. But we're not, so it doesn't.

getApplication

public ArmApplication getApplication()

Each transaction gets initialized with an instance of the ArmApplication within whose context the transaction is running.

Specified by:

getApplication in interface ArmTransaction

Returns:

an instance of ArmApplication.

getContextURIValue

public java.lang.String getContextURIValue()

Specified by:

getContextURIValue in interface ArmTransaction

getContextValue

public java.lang.String getContextValue(int index)

Specified by:

getContextValue in interface ArmTransaction

getCorrelator

public ArmCorrelator getCorrelator()

You should only call this method within a transactional scope -- that means you should always call start() first, before you call this method. If you forget, you'll get an Exception back.
Assuming you've met this precondition, however, this method will then apply the following algorithm:
-- is there a parent correlator? If yes, return it.
-- if not, is there already a local correlator? If yes, return it.
-- if not, instantiate a new correlator, and assign it to the local correlator instance variable. Subsequent calls to this method within the same transactional scope will return the instance of the local correlator.

Specified by:

getCorrelator in interface ArmTransaction

Returns:

an ArmCorrelator instance or an UnsupportedOperationException if not called within a transactional scope.

getParentCorrelator

public ArmCorrelator getParentCorrelator()

If there was a parent correlator at instantiation, you get it back with this method.

Specified by:

getParentCorrelator in interface ArmTransaction

Returns:

an ArmCorrelator or null.

getStatus

public int getStatus()

The stop(int) method requires an int parameter that represents the completion status of the transaction. The ArmConstants interface contains a handful of values that one can use for this. Each call to stop(int) sets an instance variable, which is used to retain the value of this completion status until the next time stop(int) is called. In between stop(int) calls, you can retrieve the previous status at any time by calling this method.

Specified by:

getStatus in interface ArmTransaction

Returns:

the most recent "completion status" value passed to stop(int)

getDefinition

public ArmTransactionDefinition getDefinition()

Each transaction gets initialized with an instance of the ArmTransactionDefinition that represents the type of the transaction. More weird C stuff.

Specified by:

getDefinition in interface ArmTransaction

Returns:

an instance of ArmTransactionDefinition.

getUser

public ArmUser getUser()

Specified by:

getUser in interface ArmTransaction

isTraceRequested

public boolean isTraceRequested()

Specified by:

isTraceRequested in interface ArmTransaction

reset

public int reset()

Calling this will reset all of the counters being maintained within a transactional scope.
These include:
-- start time
-- arrival time
-- trace state
-- the parent correlator

Specified by:

reset in interface ArmTransaction

Returns:

Zero. Literally. No kidding!

setArrivalTime

public int setArrivalTime()

Used to set the arrival time of the transactional scope.
Let's say you've got a transaction with a somewhat complex phase structure, and you have some sort of setup that happens immediately after the transaction starts, but before the point where you think the real action gets going. You can express this sort of a situation using the arrival time and start time attributes of the transaction together. You use the arrival time to express the start of your setup phase. Once the action is about to get going, you subsequently make a call to start(). When you later call stop(int), the difference between the arrival time and start time will be differentiated.

Specified by:

setArrivalTime in interface ArmTransaction

Returns:

Zero. Literally. No kidding!

setContextURIValue

public int setContextURIValue(java.lang.String value)

Specified by:

setContextURIValue in interface ArmTransaction

setContextValue

public int setContextValue(int index,
                           java.lang.String value)

Specified by:

setContextValue in interface ArmTransaction

setTraceRequested

public int setTraceRequested(boolean traceState)

Specified by:

setTraceRequested in interface ArmTransaction

setUser

public int setUser(ArmUser user)

Specified by:

setUser in interface ArmTransaction

start

public int start()

Used to start the clock for this transactional scope.

Specified by:

start in interface ArmTransaction

Returns:

Zero. Literally. No kidding!

start

public int start(byte[] parentCorr)

Used to start the clock for this transactional scope.

Specified by:

start in interface ArmTransaction

Parameters:

parentCorr -

Returns:

Zero. Literally. No kidding!

start

public int start(byte[] parentCorr,
                 int offset)

Deprecated. because C programmers don't like OO

This method is currently disabled in our implementation, becuase we haven't understood it yet, or found a way to translate it into a sensible Java implementation. Calling it will provoke a RuntimeException.

Specified by:

start in interface ArmTransaction

Returns:

RuntimeException

start

public int start(ArmCorrelator parentCorr)

Used to start the clock for this transactional scope.

Specified by:

start in interface ArmTransaction

Parameters:

parentCorr -

Returns:

Zero. Literally. No kidding!

stop

public int stop(int status)

Used to stop the clock for this transactional scope. This method requires an int parameter that represents the completion status of the transaction. The ArmConstants interface contains a handful of values that one can use for this. Each call to stop(int) sets an instance variable, which is used to retain the value of this completion status until the next time stop(int) is called. In between stop(int) calls, you can retrieve the previous status at any time by calling the getStatus() method.

Specified by:

stop in interface ArmTransaction

Parameters:

status - Completion status of the transaction.

Returns:

Zero. Literally. No kidding!

stop

public int stop(int status,
                java.lang.String diagnosticDetail)

Used to stop the clock for this transactional scope. This method requires an int parameter that represents the completion status of the transaction. The ArmConstants interface contains a handful of values that one can use for this. Each call to stop(int) sets an instance variable, which is used to retain the value of this completion status until the next time stop(int) is called. In between stop(int) calls, you can retrieve the previous status at any time by calling the getStatus() method.

Specified by:

stop in interface ArmTransaction

Parameters:

status - Completion status of the transaction.

diagnosticDetail - Additional message text that should be recorded with the stop.

Returns:

Zero. Literally. No kidding!

unbindThread

public int unbindThread()

Deprecated. because C programmers don't like OO

This method is currently disabled in our implementation, becuase we haven't understood it yet, or found a way to translate it into a sensible Java implementation. Calling it will provoke a RuntimeException.

Specified by:

unbindThread in interface ArmTransaction

Returns:

RuntimeException

unblocked

public int unblocked(long blockHandle)

Use this method to notify OpenArm that your transaction has stopped waiting synchronously, for some external resource. Old timers refer to this as "blocking" rather than write out "stoppedWaitingForExternalResource", which takes too many bytes... :-)

Specified by:

unblocked in interface ArmTransaction

Parameters:

blockHandle - The magic number that you got as a return value from calling blocked()

Returns:

Zero. Literally. No kidding!

update

public int update()

Use this method to notify OpenArm that your transaction is still out there and alive. Useful for long running transactions, although it would be more useful if you could pass it a String as a parameter. Then you could use the method to keep a protocol of the major steps/events within your transaction. Oh well. Being able to send a heartbeat of any kind is better than nothing...

Specified by:

update in interface ArmTransaction

Returns:

Zero. Literally. No kidding!

getStartTime

public long getStartTime()

Specified by:

getStartTime in interface TransactionState

setStartTime

public void setStartTime(long startTime)

Specified by:

setStartTime in interface TransactionState

getArrivalTime

public long getArrivalTime()

Specified by:

getArrivalTime in interface TransactionState

setArrivalTime

public void setArrivalTime(long arrivalTime)

Specified by:

setArrivalTime in interface TransactionState

getTraceState

public boolean getTraceState()

Specified by:

getTraceState in interface TransactionState

setTraceState

public void setTraceState(boolean traceState)

Specified by:

setTraceState in interface TransactionState

setParentCorrelator

public void setParentCorrelator(ArmCorrelator parentCorrelator)

Specified by:

setParentCorrelator in interface TransactionState

getBlockingHandle

public long getBlockingHandle()

Specified by:

getBlockingHandle in interface TransactionState

getId

public ArmID getId()

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class UniqueObjectImpl

hashCode

public int hashCode()

Overrides:

hashCode in class UniqueObjectImpl