public interface ArmTransactionFactory extends ArmInterface
setErrorCallback(ArmErrorCallback)
).
Semantics of the factory methods are provided in the description
of the individual methods below.
ArmMetricFactory
is instantiated using a class loader.
The actual name of the factory implementation class is obtained from the
system property whose name is provided in the
propertyKey
constant.
Error Handling Philosophy
If an invalid set of parameters is passed to any method, such as an offset
that extends beyond the end of an array, an object is returned that may
contain dummy data. For example, a null byte[] addressBytes
parameter might result in creating an object with an address of all zeros.
Different ARM implementations may handle the situation in different ways,
but in all cases, they will return an object that is syntactically
correct; that is, any of its methods can be invoked without causing an
exception, even if the data may be at least partially meaningless.
The getErrorCode()
method of each object can be used after
it is created to test whether errors occurred.
See ArmInterface
and the ARM 4.0 Java Binding specification
for a more complete explanation.
ArmTransactionFactory
also serves as the anchor point for an
application-registered callback function. setErrorCallback()
is used to register a callback that will be called if any method of an
object created by this factory object sets the error code to a negative
value. The error code is retrieved using getErrorCode()
,
defined in ArmInterface
, the root for most interfaces in
the ARM specification. The boolean
returned by
setErrorCallback()
indicates whether the registration is
accepted. If an ARM implementation does not support the callback
function, it will return false. setErrorCallback(null)
unregisters any previously registered callback. Note that due to timing
conditions or specifics of the ARM implementation, a previously
registered callback may continue to be called for an indeterminate
length of time after setErrorCallback(null)
is executed.
For a broader discussion of error handling, refer to the ARM 4.0 Java
Binding specification.Modifier and Type | Field and Description |
---|---|
static java.lang.String |
propertyKey
name of system property holding the implementation class name.
|
Modifier and Type | Method and Description |
---|---|
ArmApplication |
newArmApplication(ArmApplicationDefinition definition,
java.lang.String group,
java.lang.String instance,
java.lang.String[] contextValues)
Creates the
ArmApplication object to which
transaction instances are related. |
ArmApplicationDefinition |
newArmApplicationDefinition(java.lang.String name,
ArmIdentityProperties identityProperties,
ArmID id)
Creates the
ArmApplicationDefinition object that
describes the metadata about an application. |
ArmCorrelator |
newArmCorrelator(byte[] corrBytes)
Creates a correlator from a byte array in the correct format.
|
ArmCorrelator |
newArmCorrelator(byte[] corrBytes,
int offset)
Creates a correlator from a byte array in the correct format.
|
ArmID |
newArmID(byte[] idBytes)
Creates the objects that contain an immutable 16-byte ID.
|
ArmID |
newArmID(byte[] idBytes,
int offset)
Creates the objects that contain an immutable 16-byte ID.
|
ArmIdentityProperties |
newArmIdentityProperties(java.lang.String[] identityNames,
java.lang.String[] identityValues,
java.lang.String[] contextNames)
Creates an object that contains an immutable set of identity
property names and values, and an immutable set of context property
names.
|
ArmIdentityPropertiesTransaction |
newArmIdentityPropertiesTransaction(java.lang.String[] identityNames,
java.lang.String[] identityValues,
java.lang.String[] contextNames,
java.lang.String uriValue)
Creates an object that extends
newArmIdentityProperties
to also include a URI property, which is also immutable. |
ArmTransaction |
newArmTransaction(ArmApplication app,
ArmTransactionDefinition definition)
Creates an object that represents an instance of a transaction.
|
ArmTransactionDefinition |
newArmTransactionDefinition(ArmApplicationDefinition app,
java.lang.String name,
ArmIdentityPropertiesTransaction identityProperties,
ArmID id)
Creates an object that represents the metadata about a transaction.
|
ArmUser |
newArmUser(java.lang.String name,
ArmID id)
Creates an ArmUser object that represents the user who invoked
(directly or indirectly) the transaction.
|
boolean |
setErrorCallback(ArmErrorCallback errorCallback)
Registers an error callback for objects created through this factory.
|
getErrorCode, getErrorMessage, setErrorCode
static final java.lang.String propertyKey
ArmApplication newArmApplication(ArmApplicationDefinition definition, java.lang.String group, java.lang.String instance, java.lang.String[] contextValues)
ArmApplication
object to which
transaction instances are related.
definition
is the only required non-null
parameter.definition
- metadata describing the type of the ARM application.
Must not be null
.group
- Name of the group the application belongs to.
May be null
.instance
- Name this application instance is given.
May be null
.contextValues
- An array of strings providing the value parts of
(name,value) context properties.
May be null
.ArmApplication
instance.ArmApplication
ArmApplicationDefinition newArmApplicationDefinition(java.lang.String name, ArmIdentityProperties identityProperties, ArmID id)
ArmApplicationDefinition
object that
describes the metadata about an application.
That is, the descriptive data that is the same for all
instances of the same application.
name
is the only required non-null
parameter.name
- the name of the application type. A name should be chosen
that is unique.
Must not be null
identityProperties
- a set of properties contibuting to the
identity of the application definition.
May be null
.
See newArmIdentityProperties(java.lang.String[], java.lang.String[], java.lang.String[])
.id
- An optional 16-byte ID associated with the identity of
the application definition.ArmApplicationDefinition
.ArmApplicationDefinition
ArmCorrelator newArmCorrelator(byte[] corrBytes)
ArmConstants.ARM_CORR_MAX_LENGTH
.
If the correlator is longer than the ARM implementation supports,
an ArmCorrelator
object will be created, but
it may contain dummy data, at the discretion of the ARM implementation.corrBytes
- a byte array containig correlator data.ArmCorrelator
.ArmCorrelator
ArmCorrelator newArmCorrelator(byte[] corrBytes, int offset)
newArmCorrelator(byte[])
. Since
the start of the correlator bytes within the array is at
position offset
, the length of the correlator is taken
from the bytes at offset
and offset+1
.corrBytes
- a byte array containig correlator data.offset
- start of the correlator bytes within the array.ArmCorrelator
.ArmID newArmID(byte[] idBytes)
idBytes
- a byte array containig ID data.ArmID
.ArmID
ArmID newArmID(byte[] idBytes, int offset)
newArmID(byte[])
.idBytes
- a byte array containig ID data.offset
- start of the ID bytes within the array.ArmID
.ArmIdentityProperties newArmIdentityProperties(java.lang.String[] identityNames, java.lang.String[] identityValues, java.lang.String[] contextNames)
null
reference and a zero-length string are both
treated as a null element. It is permissible to have null elements
in the middle of the array. For example, it is permissible for the
elements at indices 0 and 19 to be non-null
and all
the elements from indices 1 to 18 to be null
.
The arrays are position sensitive.
The identity property name and value arrays should contain the same
number of elements at the same array indices; for each
non-null
name or value, there should be a corresponding
non-null
value or name, respectively, at the same array
index. For any array index, if either the name or the value is
null
, both the name and the value are ignored.
The context property names are provided in this object. The
context values are provided in an ArmApplication
,
ArmTransaction
or ArmTranReport
object.
If the name at an array index is null
, the
corresponding value in those objects is ignored.identityNames
- an array of identity property names.identityValues
- an array of identity property values.contextNames
- an array of identity property names.ArmIdentityProperties
ArmIdentityPropertiesTransaction newArmIdentityPropertiesTransaction(java.lang.String[] identityNames, java.lang.String[] identityValues, java.lang.String[] contextNames, java.lang.String uriValue)
newArmIdentityProperties
to also include a URI property, which is also immutable.
See the newArmIdentityProperties(java.lang.String[], java.lang.String[], java.lang.String[])
description for all
other parameters.identityNames
- an array of identity property names.identityValues
- an array of identity property values.contextNames
- an array of identity property names.uriValue
- the URI property value.ArmIdentityPropertiesTransaction
ArmTransaction newArmTransaction(ArmApplication app, ArmTransactionDefinition definition)
app
- the application instance the transaction belongs to.definition
- the metadata describing the type of the transaction.ArmTransaction
instance.ArmTransaction
ArmTransactionDefinition newArmTransactionDefinition(ArmApplicationDefinition app, java.lang.String name, ArmIdentityPropertiesTransaction identityProperties, ArmID id)
app
- the metadata describing the type of the containing
application.
Must not be null
.name
- the name of the transaction type. A name should be chosen
that is unique.
Must not be null
.identityProperties
- a set of properties contibuting to the
identity of the transaction definition.
May be null
.
See newArmIdentityProperties(java.lang.String[], java.lang.String[], java.lang.String[])
.id
- An optional 16-byte ID associated with the identity of
the transaction definition.ArmTransactionDefinition
.ArmTransactionDefinition
ArmUser newArmUser(java.lang.String name, ArmID id)
name
- name of the user.id
- An optional 16-byte ID associated with the user.ArmUser
object.ArmUser
boolean setErrorCallback(ArmErrorCallback errorCallback)
errorCallback
- an application object implementing the
ArmErrorCallback> interface.
true
if registration is accepted.