Public Member Functions | Static Public Attributes

org.opengroup.arm40.transaction.ArmTransactionFactory Interface Reference
[ARM 4.0 Factories]

Provides methods to create instances of the classes in the org.opengroup.arm40.transaction package. More...

Inheritance diagram for org.opengroup.arm40.transaction.ArmTransactionFactory:
org.opengroup.arm40.transaction.ArmInterface

List of all members.

Public Member Functions

ArmApplication newArmApplication (ArmApplicationDefinition definition, String group, String instance, String[] contextValues)
 Creates the ArmApplication object to which transaction instances are related.
ArmApplicationDefinition newArmApplicationDefinition (String name, ArmIdentityProperties identityProperties, ArmID id)
 Creates the ArmApplicationDefinition object that describes the metadata about an application.
ArmBlockCause newArmBlockCause ()
 Creates an ArmBlockCause.
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 (String[] identityNames, String[] identityValues, 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 (String[] identityNames, String[] identityValues, String[] contextNames, 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, String name, ArmIdentityPropertiesTransaction identityProperties, ArmID id)
 Creates an object that represents the metadata about a transaction.
ArmUser newArmUser (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.

Static Public Attributes

static final String propertyKey = "Arm40.ArmTransactionFactory"
 name of system property holding the implementation class name.

Detailed Description

Provides methods to create instances of the classes in the org.opengroup.arm40.transaction package.

An error callback method can be registered for objects created with this factory (see 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.

Author:
ARM Working Group of The Open Group

Member Function Documentation

ArmApplication org.opengroup.arm40.transaction.ArmTransactionFactory.newArmApplication ( ArmApplicationDefinition  definition,
String  group,
String  instance,
String[]  contextValues 
)

Creates the ArmApplication object to which transaction instances are related.

definition is the only required non-null parameter.

See also:
ArmApplication
Parameters:
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.
Returns:
a new ArmApplication instance.
ArmApplicationDefinition org.opengroup.arm40.transaction.ArmTransactionFactory.newArmApplicationDefinition ( String  name,
ArmIdentityProperties  identityProperties,
ArmID  id 
)

Creates the 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.

See also:
ArmApplicationDefinition
Parameters:
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.
id An optional 16-byte ID associated with the identity of the application definition.
Returns:
a new ArmApplicationDefinition.
ArmBlockCause org.opengroup.arm40.transaction.ArmTransactionFactory.newArmBlockCause (  ) 

Creates an ArmBlockCause.

It takes no parameters - all its properties are set via setter methods.

Returns:
a new ArmBlockCause.
Since:
ARM 4.1
ArmCorrelator org.opengroup.arm40.transaction.ArmTransactionFactory.newArmCorrelator ( byte[]  corrBytes  ) 

Creates a correlator from a byte array in the correct format.

No length field is passed to this method because ARM requires that the length of the correlator be found in the first two bytes (in network byte order) of the byte array. The correlator must be no longer than 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.

See also:
ArmCorrelator
Parameters:
corrBytes a byte array containig correlator data.
Returns:
a new ArmCorrelator.
ArmCorrelator org.opengroup.arm40.transaction.ArmTransactionFactory.newArmCorrelator ( byte[]  corrBytes,
int  offset 
)

Creates a correlator from a byte array in the correct format.

See description of newArmCorrelator(byte[] corrBytes). 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.

Parameters:
corrBytes a byte array containig correlator data.
offset start of the correlator bytes within the array.
Returns:
a new ArmCorrelator.
ArmID org.opengroup.arm40.transaction.ArmTransactionFactory.newArmID ( byte[]  idBytes  ) 

Creates the objects that contain an immutable 16-byte ID.

Having 16-byte IDs accommodates some widely used IDs, such as the UUID (universally unique identifier) defined in the DCE and IETF standards.

See also:
ArmID
Parameters:
idBytes a byte array containig ID data.
Returns:
a new ArmID.
ArmID org.opengroup.arm40.transaction.ArmTransactionFactory.newArmID ( byte[]  idBytes,
int  offset 
)

Creates the objects that contain an immutable 16-byte ID.

See description of newArmID(byte[] idBytes).

Parameters:
idBytes a byte array containig ID data.
offset start of the ID bytes within the array.
Returns:
a new ArmID.
ArmIdentityProperties org.opengroup.arm40.transaction.ArmTransactionFactory.newArmIdentityProperties ( String[]  identityNames,
String[]  identityValues,
String[]  contextNames 
)

Creates an object that contains an immutable set of identity property names and values, and an immutable set of context property names.

These properties describe identity properties that are common to all instances of an application or transaction.

The names and values are provided in arrays of strings. There can be up to twenty elements in each of the arrays. A 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.

See also:
ArmIdentityProperties
Parameters:
identityNames an array of identity property names.
identityValues an array of identity property values.
contextNames an array of identity property names.
Returns:
a new ArmIdentityProperties object.
ArmIdentityPropertiesTransaction org.opengroup.arm40.transaction.ArmTransactionFactory.newArmIdentityPropertiesTransaction ( String[]  identityNames,
String[]  identityValues,
String[]  contextNames,
String  uriValue 
)

Creates an object that extends newArmIdentityProperties to also include a URI property, which is also immutable.

See the newArmIdentityProperties description for all other parameters.

See also:
ArmIdentityPropertiesTransaction
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.
Returns:
a new ArmIdentityPropertiesTransaction object.
ArmTransaction org.opengroup.arm40.transaction.ArmTransactionFactory.newArmTransaction ( ArmApplication  app,
ArmTransactionDefinition  definition 
)

Creates an object that represents an instance of a transaction.

See also:
ArmTransaction
Parameters:
app the application instance the transaction belongs to.
definition the metadata describing the type of the transaction.
Returns:
a new ArmTransaction instance.
ArmTransactionDefinition org.opengroup.arm40.transaction.ArmTransactionFactory.newArmTransactionDefinition ( ArmApplicationDefinition  app,
String  name,
ArmIdentityPropertiesTransaction  identityProperties,
ArmID  id 
)

Creates an object that represents the metadata about a transaction.

See also:
ArmTransactionDefinition
Parameters:
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.
id An optional 16-byte ID associated with the identity of the transaction definition.
Returns:
a new ArmTransactionDefinition.
ArmUser org.opengroup.arm40.transaction.ArmTransactionFactory.newArmUser ( String  name,
ArmID  id 
)

Creates an ArmUser object that represents the user who invoked (directly or indirectly) the transaction.

See also:
ArmUser
Parameters:
name name of the user.
id An optional 16-byte ID associated with the user.
Returns:
a new ArmUser object.
boolean org.opengroup.arm40.transaction.ArmTransactionFactory.setErrorCallback ( ArmErrorCallback  errorCallback  ) 

Registers an error callback for objects created through this factory.

See the error handling philosophy comment in the description of this interface.

Parameters:
errorCallback an application object implementing the ArmErrorCallback interface.
Returns:
true if registration is accepted.
The documentation for this interface was generated from the following file:
  • org/opengroup/arm40/transaction/ArmTransactionFactory.java
MyARM
Documentation generated on Thu May 24 2018 22:24:15. © 2018 by MyARM GmbH