Hemi JavaScript Framework
Hemi.transaction
Description
The Transaction Service provides an object-level communication bus. Unlike events, delegates, and message subscriptions and publications, the transaction service coordinates disimilar objects on a common band. Non Framework Objects may be decorated with the Transaction Participant API, and allow cross-Framework coordination.
Class Index
static Hemi.transaction.service
version 3.1.9
Static instance of the serviceImpl class.
static Hemi.transaction.TransactionParticipant
version 3.1.9
This static class describes the interface an object must expose to participate in the TransactionService. A participant must be registered with the ObjectRegistry. The addServiceAPI method may be used to instrument this API for quick access to the service.
Index
Method Index
Methods
doTransaction
Processes the served transaction packet.
Syntax
z = doTransaction(
s, p
)
Parameters
- s as TransactionService : The TransactionService object handling this transaction.
- p as TransactionPacket : The packet being served.
Returns
z as boolean: Always returns false.
endTransaction
Ends the transaction for the specified packet.
Syntax
void endTransaction(
s, p
)
Parameters
- s as TransactionService : The TransactionService object handling this transaction.
- p as TransactionPacket : The packet for this transaction.
startTransaction
Starts the transaction for the specified packet.
Syntax
void startTransaction(
s, p
)
Parameters
- s as TransactionService : The TransactionService object handling this transaction.
- p as TransactionPacket : The packet for this transaction.
Hemi.transaction.TransactionPacket
version 3.1.9
This is an abstract class generated by the TransactionService. It has no public initializer or constructor.
Index
Property Index
- public data: The packet data.
- public errors: Variable use property.
- public is_finalized: Bit indicating whether the packet has been finalized.
- public is_open: Bit indicating whether the packet is open.
- public owner_id: Identifier of the registered object that owns the packet.
- public packet_id: The unique identifer of the packet.
- public packet_name: The name of the packet.
- public packet_state: Variable use property.
- public participant_count: Number of participants currently using this packet.
- public participants: Hash of object identifiers that are participating in the transaction for this packet. The hash key is the object identifier, and the hash value is the participant state. State values are: 0 = not participating / transaction ended, 1 = participating, 2 = participated and completed with a positive (true) response.
- public serve_type: The type of service this packet will receive. 1 indicates the packet will be served untill all participants return true from doTransaction. 2 indicates the packet is only served once.
- public service_id: The unique identifier of the service to which this packet belongs.
Method Index
Properties
data
The packet data.
Syntax
variant = object.data
object.data = variant
errors
Variable use property.
Syntax
int = object.errors
object.errors = int
is_finalized
Bit indicating whether the packet has been finalized.
Syntax
boolean = object.is_finalized
is_open
Bit indicating whether the packet is open.
Syntax
boolean = object.is_open
owner_id
Identifier of the registered object that owns the packet.
Syntax
String = object.owner_id
packet_id
The unique identifer of the packet.
Syntax
String = object.packet_id
packet_name
The name of the packet.
Syntax
String = object.packet_name
packet_state
Variable use property.
Syntax
int = object.packet_state
object.packet_state = int
participant_count
Number of participants currently using this packet.
Syntax
int = object.participant_count
participants
Hash of object identifiers that are participating in the transaction for this packet. The hash key is the object identifier, and the hash value is the participant state. State values are: 0 = not participating / transaction ended, 1 = participating, 2 = participated and completed with a positive (true) response.
Syntax
hash = object.participants
serve_type
The type of service this packet will receive. 1 indicates the packet will be served untill all participants return true from doTransaction. 2 indicates the packet is only served once.
Syntax
int = object.serve_type
service_id
The unique identifier of the service to which this packet belongs.
Syntax
String = object.service_id
Methods
setBlockEndTransaction
Specifies whether the packet should be served during endTransaction.
Syntax
void setBlockEndTransaction(
b
)
Parameters
- b as boolean : Bit indicating whether the packet is blocked from being served during
setBlockServeTransaction
Specifies whether the packet should be served during serveTransaction.
Syntax
void setBlockServeTransaction(
b
)
Parameters
- b as boolean : Bit indicating whether the packet is blocked from being served during
setBlockStartTransaction
Specifies whether the packet should be served during startTransaction.
Syntax
void setBlockStartTransaction(
b
)
Parameters
- b as boolean : Bit indicating whether the packet is blocked from being served during
setServeType
Sets the packet serve type.
Syntax
void setServeType(
i
)
Parameters
- i as int : The type of service this packet will receive. 1 indicates the packet will be served untill all participants return true from
static Hemi.transaction.transaction
version 3.1.9
Static instance of the serviceImpl class.
Index
Method Index
- virtual _handle_begin_transaction: Invoked when the transaction for the specified packet begins.
- virtual _handle_end_transaction: Invoked when the transaction for the specified packet ends.
- virtual _handle_packettype: Processes the served transaction packet for the specified type. IE if a packet has the type 'custompacket', then you can define a method named _handle_custompacket
- virtual _handle_transaction: Processes the served transaction packet.
- public addServiceAPI: Injects the required API for working with transactions onto the target object.
- virtual doTransaction: Processes the served transaction packet. Automatically invokes _handle_transaction, if it was defined. Also will invoke _handle_packettype if defined. IE if a packet has the type 'custompacket', then you can define a method named _handle_custompacket
- virtual endTransaction: Ends the transaction for the specified packet. Automatically invokes _handle_end_transaction if defined.
- virtual getPacket: Returns the transaction packet associated with this component.
- virtual joinTranactionPacket: Joins the object to the packet, and returns the packet identifier.
- virtual removeFromTransactionPacket: Removes the object from the packet.
- virtual serveTransaction: Serves the transaction packet to transaction participants.
- virtual startTransaction: Starts the transaction for the specified packet. Automatically invokes _handle_begin_transaction if defined.
Methods
_handle_begin_transaction
Invoked when the transaction for the specified packet begins. Method is virtual and can be overridden.
Syntax
void _handle_begin_transaction(
s, p
)
Parameters
- s as TransactionService : The TransactionService object handling this transaction.
- p as TransactionPacket : The packet being served.
_handle_end_transaction
Invoked when the transaction for the specified packet ends. Method is virtual and can be overridden.
Syntax
void _handle_end_transaction(
s, p
)
Parameters
- s as TransactionService : The TransactionService object handling this transaction.
- p as TransactionPacket : The packet being served.
_handle_packettype
Processes the served transaction packet for the specified type. IE if a packet has the type 'custompacket', then you can define a method named _handle_custompacket Method is virtual and can be overridden.
Syntax
void _handle_packettype(
s, p
)
Parameters
- s as TransactionService : The TransactionService object handling this transaction.
- p as TransactionPacket : The packet being served.
_handle_transaction
Processes the served transaction packet. Method is virtual and can be overridden.
Syntax
void _handle_transaction(
s, p
)
Parameters
- s as TransactionService : The TransactionService object handling this transaction.
- p as TransactionPacket : The packet being served.
addServiceAPI
Injects the required API for working with transactions onto the target object.
Syntax
b = addServiceAPI(
o
)
Parameters
- o as Object : Object onto which to inject helper methods for working with transactions.
Returns
b as boolean: Bit indicating whether the service API was injected where otherwise not defined.
doTransaction
Processes the served transaction packet. Automatically invokes _handle_transaction, if it was defined. Also will invoke _handle_packettype if defined. IE if a packet has the type 'custompacket', then you can define a method named _handle_custompacket Method is virtual and can be overridden.
Syntax
z = doTransaction(
s, p
)
Parameters
- s as TransactionService : The TransactionService object handling this transaction.
- p as TransactionPacket : The packet being served.
Returns
z as boolean: Always returns false.
endTransaction
Ends the transaction for the specified packet. Automatically invokes _handle_end_transaction if defined. Method is virtual and can be overridden.
Syntax
z = endTransaction(
s, p
)
Parameters
- s as TransactionService : The TransactionService object handling this transaction.
- p as TransactionPacket : The packet for this transaction.
Returns
z as boolean: Always returns true.
getPacket
Returns the transaction packet associated with this component. Method is virtual and can be overridden.
Syntax
p = getPacket(
)
Returns
p as TransactionPacket: TransactionPacket object.
joinTranactionPacket
Joins the object to the packet, and returns the packet identifier. Method is virtual and can be overridden.
Syntax
sPacketId = joinTranactionPacket(
s
)
Parameters
- s as String : The packet name.
Returns
sPacketId as String: The transaction packet identifier.
removeFromTransactionPacket
Removes the object from the packet. Method is virtual and can be overridden.
Syntax
sPacketId = removeFromTransactionPacket(
s
)
Parameters
- s as String : The packet name.
Returns
sPacketId as String: The transaction packet identifier.
serveTransaction
Serves the transaction packet to transaction participants. Method is virtual and can be overridden.
Syntax
z = serveTransaction(
t, s, b, n
)
Parameters
- t as variant : Variant value used to identify the type of the packet.
- s as variant : Variant value used to identify the source of the packet.
- b as boolean : Bit indicating whether the packet should be served to the owner.
- n as String : Packet name.
Returns
z as boolean: Returns true if a packet exists and was served, false otherwise.
startTransaction
Starts the transaction for the specified packet. Automatically invokes _handle_begin_transaction if defined. Method is virtual and can be overridden.
Syntax
z = startTransaction(
s, p
)
Parameters
- s as TransactionService : The TransactionService object handling this transaction.
- p as TransactionPacket : The packet for this transaction.
Returns
z as boolean: Always returns true.
Hemi.transaction.serviceImpl
version 3.1.9
A class for managing communication between objects implementing the TransactionParticipant API, and using TransactionPacket objects.
Index
Method Index
- public addTransactionParticipant: Adds an object to participate with the specified TransactionPacket.
- public canRegister: Tests an object to determine if it can be registered.
- public closeTransaction: Closes the transaction represented by the specified TransactionPacket.
- public getPacket: Returns the specified TransactionPacket object.
- public getPacketByName: Returns the specified TransactionPacket object.
- public getPackets: Returns an array of TransactionPacket objects.
- public getRegisteredObjects: Returns an array of object identifiers that are registered with the TransactionService.
- public getRegisteredObjectsMap: Returns a hashmap of object identifiers and the index into the registered objects array.
- public isPacket: Returns true if the specified name exists.
- public isRegistered: Returns whether an object is registered..
- public newTransactionPacket (internal): Creates a new TransactionPacket.
- public openTransaction: Opens a new transaction and returns the TransactionPacket identifier.
- public register: Registers an object with the transaction service.
- public removeTransactionParticipant: Removes an object from participating with the specified TransactionPacket.
- public removeTransactionParticipants: Removes object from all transaction participations.
- public serveTransaction: Serves the specified TransactionPacket to its participants.
- public sigterm: Sends a termination signal to the service, and closes all open packets.
- public unregister: Unregisters an object with the transaction service.
Methods
addTransactionParticipant
Adds an object to participate with the specified TransactionPacket.
Syntax
b = addTransactionParticipant(
o, p
)
Parameters
- o as TransactionParticipant : Object that is registered with the TransactionService.
- p as TransactionPacket : TransactionPacket with which the specified object should participate.
Returns
b as boolean: True if the object is participating with the packet, otherwise false.
canRegister
Tests an object to determine if it can be registered.
Syntax
b = canRegister(
o
)
Parameters
- o as object : Object to test whether or not it can be registered.
Returns
b as boolean: True if the object can be registered, otherwise false.
closeTransaction
Closes the transaction represented by the specified TransactionPacket.
Syntax
void closeTransaction(
i
)
Parameters
- i as String : Name of the TransactionPacket.
getPacket
Returns the specified TransactionPacket object.
Syntax
e = getPacket(
i
)
Parameters
- i as int : Index of the TransactionPacket object..
Returns
e as TransactionPacket: XHTMLForm object.
getPacketByName
Returns the specified TransactionPacket object.
Syntax
e = getPacketByName(
n
)
Parameters
- n as String : Name of the element.
Returns
e as TransactionPacket: TransactionPacket object.
getPackets
Returns an array of TransactionPacket objects.
Syntax
a = getPackets(
)
Returns
a as array: Array of TransactionPacket objects.
getRegisteredObjects
Returns an array of object identifiers that are registered with the TransactionService.
Syntax
a = getRegisteredObjects(
)
Returns
a as array: Array of object identifiers
getRegisteredObjectsMap
Returns a hashmap of object identifiers and the index into the registered objects array.
Syntax
a = getRegisteredObjectsMap(
)
Returns
a as array: Hashmap of object identifiers
isPacket
Returns true if the specified name exists.
Syntax
b = isPacket(
i
)
Parameters
- i as variant : Name or index of the TransactionPacket object..
Returns
b as boolean: Bit indicating whether the specified object name exists.
isRegistered
Returns whether an object is registered..
Syntax
b = isRegistered(
o
)
Parameters
- o as object : Object to test whether or not it is registered.
Returns
b as boolean: True if the object is registered, otherwise false.
newTransactionPacket
Creates a new TransactionPacket.
Syntax
p = newTransactionPacket(
i, n, o, v, f
)
Parameters
- i as String : Packet identifier.
- n as String : Packet name.
- o as String : Owner id.
- v as object : Variant data.
- f as function : Packet finalization handler.
Returns
p as TransactionPacket: A new TransactionPacket.
openTransaction
Opens a new transaction and returns the TransactionPacket identifier.
Syntax
i = openTransaction(
n, p, d, f
)
Parameters
- n as String : Name of the transaction.
- p as TransactionParticipant (optional): Parent object.
- d as variant (optional): Data associated with the transaction.
- f as function (optional): Function to invoke when transaction completes and the TransactionPacket is finalized.
Returns
i as String: Identifier of the new TransactionPacket.
register
Registers an object with the transaction service.
Syntax
b = register(
o, b
)
Parameters
- o as object : Object to register with the TransactionService.
- b as boolean (optional): Bit indicating the object should be instrumented with the transaction API.
Returns
b as boolean: True if the object was registered, otherwise false.
removeTransactionParticipant
Removes an object from participating with the specified TransactionPacket.
Syntax
b = removeTransactionParticipant(
o, p
)
Parameters
- o as TransactionParticipant : Object that is registered with the TransactionService.
- p as TransactionPacket : TransactionPacket with which the specified object is participating.
Returns
b as boolean: True if the object was removed from participating with the packet, otherwise false.
removeTransactionParticipants
Removes object from all transaction participations.
Syntax
void removeTransactionParticipants(
o
)
Parameters
- o as TransactionParticipant : Object that is registered with the TransactionService.
serveTransaction
Serves the specified TransactionPacket to its participants.
Syntax
b = serveTransaction(
p, i, b
)
Parameters
- p as TransactionPacket : TransactionPacket with which the specified object is participating.
- i as String (optional): Identifier of the object that should act as the controller of the packet. Defaults to the packet owner.
- b as boolean (optional): Skip serving the packet to the controller.
Returns
b as boolean: True if the packet was served, otherwise false.
sigterm
Sends a termination signal to the service, and closes all open packets.
Syntax
void sigterm(
)
unregister
Unregisters an object with the transaction service.
Syntax
b = unregister(
o
)
Parameters
- o as object : Object to register with the TransactionService.
Returns
b as boolean: True if the object was unregistered, otherwise false.
[ Hemi JavaScript Framework - Stephen W. Cote, 2002 - 2011. ]