From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- .../doc/src/CosTransactions_Control.xml | 73 ++++++ .../doc/src/CosTransactions_Coordinator.xml | 229 +++++++++++++++++ .../src/CosTransactions_RecoveryCoordinator.xml | 82 ++++++ .../doc/src/CosTransactions_Resource.xml | 128 ++++++++++ ...CosTransactions_SubtransactionAwareResource.xml | 75 ++++++ .../doc/src/CosTransactions_Synchronization.xml | 69 +++++ .../doc/src/CosTransactions_Terminator.xml | 72 ++++++ .../doc/src/CosTransactions_TransactionFactory.xml | 64 +++++ .../src/CosTransactions_TransactionalObject.xml | 42 ++++ lib/cosTransactions/doc/src/Makefile | 229 +++++++++++++++++ lib/cosTransactions/doc/src/book.gif | Bin 0 -> 1081 bytes lib/cosTransactions/doc/src/book.xml | 48 ++++ lib/cosTransactions/doc/src/ch_contents.xml | 74 ++++++ lib/cosTransactions/doc/src/ch_example.xml | 280 +++++++++++++++++++++ lib/cosTransactions/doc/src/ch_install.xml | 103 ++++++++ lib/cosTransactions/doc/src/ch_introduction.xml | 64 +++++ lib/cosTransactions/doc/src/ch_skeletons.xml | 213 ++++++++++++++++ lib/cosTransactions/doc/src/cosTransactions.xml | 141 +++++++++++ lib/cosTransactions/doc/src/fascicules.xml | 18 ++ lib/cosTransactions/doc/src/make.dep | 27 ++ lib/cosTransactions/doc/src/notes.gif | Bin 0 -> 2005 bytes lib/cosTransactions/doc/src/notes.xml | 243 ++++++++++++++++++ lib/cosTransactions/doc/src/part.xml | 40 +++ lib/cosTransactions/doc/src/part_notes.xml | 36 +++ lib/cosTransactions/doc/src/ref_man.gif | Bin 0 -> 1530 bytes lib/cosTransactions/doc/src/ref_man.xml | 43 ++++ lib/cosTransactions/doc/src/summary.html.src | 1 + lib/cosTransactions/doc/src/user_guide.gif | Bin 0 -> 1581 bytes 28 files changed, 2394 insertions(+) create mode 100644 lib/cosTransactions/doc/src/CosTransactions_Control.xml create mode 100644 lib/cosTransactions/doc/src/CosTransactions_Coordinator.xml create mode 100644 lib/cosTransactions/doc/src/CosTransactions_RecoveryCoordinator.xml create mode 100644 lib/cosTransactions/doc/src/CosTransactions_Resource.xml create mode 100644 lib/cosTransactions/doc/src/CosTransactions_SubtransactionAwareResource.xml create mode 100644 lib/cosTransactions/doc/src/CosTransactions_Synchronization.xml create mode 100644 lib/cosTransactions/doc/src/CosTransactions_Terminator.xml create mode 100644 lib/cosTransactions/doc/src/CosTransactions_TransactionFactory.xml create mode 100644 lib/cosTransactions/doc/src/CosTransactions_TransactionalObject.xml create mode 100644 lib/cosTransactions/doc/src/Makefile create mode 100644 lib/cosTransactions/doc/src/book.gif create mode 100644 lib/cosTransactions/doc/src/book.xml create mode 100644 lib/cosTransactions/doc/src/ch_contents.xml create mode 100644 lib/cosTransactions/doc/src/ch_example.xml create mode 100644 lib/cosTransactions/doc/src/ch_install.xml create mode 100644 lib/cosTransactions/doc/src/ch_introduction.xml create mode 100644 lib/cosTransactions/doc/src/ch_skeletons.xml create mode 100644 lib/cosTransactions/doc/src/cosTransactions.xml create mode 100644 lib/cosTransactions/doc/src/fascicules.xml create mode 100644 lib/cosTransactions/doc/src/make.dep create mode 100644 lib/cosTransactions/doc/src/notes.gif create mode 100644 lib/cosTransactions/doc/src/notes.xml create mode 100644 lib/cosTransactions/doc/src/part.xml create mode 100644 lib/cosTransactions/doc/src/part_notes.xml create mode 100644 lib/cosTransactions/doc/src/ref_man.gif create mode 100644 lib/cosTransactions/doc/src/ref_man.xml create mode 100644 lib/cosTransactions/doc/src/summary.html.src create mode 100644 lib/cosTransactions/doc/src/user_guide.gif (limited to 'lib/cosTransactions/doc/src') diff --git a/lib/cosTransactions/doc/src/CosTransactions_Control.xml b/lib/cosTransactions/doc/src/CosTransactions_Control.xml new file mode 100644 index 0000000000..f4d9a38d13 --- /dev/null +++ b/lib/cosTransactions/doc/src/CosTransactions_Control.xml @@ -0,0 +1,73 @@ + + + + +
+ + 1999 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + CosTransactions_Control + Niclas Eklund + Niclas Eklund + + Niclas Eklund + + 1999-04-12 + PA1 +
+ CosTransactions_Control + This module implements the OMG CosTransactions::Control interface. + +

To get access to the record definitions for the structures use:

+-include_lib("cosTransactions/include/CosTransactions.hrl").

+ + + + get_coordinator(Control) -> Return + Return the Coordinator object associated with the target object + + Control = #objref + Return = Coordinator | {'EXCEPTION', E} + Coordinator = #objref + E = #'CosTransactions_Unavailable' {} + + +

This operation returns the Coordinator object associated with the target object. + The Coordinator supports operations for termination of a transaction.

+ + + + get_terminator(Control) -> Return + Return the Terminator object associated with the target object + + Control = #objref + Return = Terminator | {'EXCEPTION', E} + Terminator = #objref + E = #'CosTransactions_Unavailable' {} + + +

This operation returns the Terminator object associated with the target object. + The Terminator supports operations for termination of a transaction.

+ + + + + + diff --git a/lib/cosTransactions/doc/src/CosTransactions_Coordinator.xml b/lib/cosTransactions/doc/src/CosTransactions_Coordinator.xml new file mode 100644 index 0000000000..e172951e4e --- /dev/null +++ b/lib/cosTransactions/doc/src/CosTransactions_Coordinator.xml @@ -0,0 +1,229 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + CosTransactions_Coordinator + + + + 1999-04-12 + PA1 +
+ CosTransactions_Coordinator + This module implements the OMG CosTransactions::Coordinator interface. + +

To get access to the record definitions for the structures use:

+-include_lib("cosTransactions/include/CosTransactions.hrl").

+ + + + create_subtransaction(Coordinator) -> Control + Create a new subtransaction. + + Coordinator = #objref + Control = #objref + + +

A new subtransaction is created whose parent is the Coordinator argument.

+

Raises exception:

+ + 'SubtransactionsUnavailable' - if nested transactions are not supported. + 'Inactive' - if target transaction has already been prepared. + + + + + get_transaction_name(Coordinator) -> Name + Return the name associated with the object. + + Coordinator = #objref + Name = string() of type "oe_name@machine_type_timestamp" + + +

Returns a printable string, which describe the transaction. The main purpose is to support debugging.

+ + + + get_parent_status(Coordinator) -> Status + Return the status of the parent transaction. + + Coordinator = #objref + Status = atom() + + +

Returns the status of the parent transaction + associated with the target object. If the target object is a top-level + transaction this operation is equivalent to get_status/1 operation.

+

Possible Status replies:

+ + 'StatusCommitted' + 'StatusCommitting' + 'StatusMarkedRollback' + 'StatusRollingBack' + 'StatusRolledBack' + 'StatusActive' + 'StatusPrepared' + 'StatusUnknown' + 'StatusNoTransaction' + 'StatusPreparing' + + + + + get_status(Coordinator) -> Status + Return the status of the transaction associated with the target object + + Coordinator = #objref + Status = atom() + + +

Returns the status of the transaction associated with the target object.

+ + + + get_top_level_status(Coordinator) -> Status + Return the status of the top-level transaction associated with the target object + + Coordinator = #objref + Status = atom() + + +

Returns the status of the top-level transaction associated with the target object.

+ + + + hash_top_level_tran(Coordinator) -> Return + Return a hash code for the top-level transaction associated with the target object + + Coordinator = #objref + Return = integer() + + +

Returns a hash code for the top-level transaction + associated with the target object. Equals the operation + hash_transaction/1 if the target object is a top-level transaction.

+ + + + hash_transaction(Coordinator) -> Return + Return a hash code for the transaction associated with the target object. + + Coordinator = #objref + Return = integer() + + +

Returns a hash code for the transaction associated with the target object.

+ + + + is_descendant_transaction(Coordinator, OtherCoordinator) -> Return + Return a boolean which indicates whether the transaction associated with the target object is a descendant of the transaction associated with the parameter object + + Coordinator = #objref + OtherCoordinator = #objref + Return = Boolean + + +

Returns true if the transaction associated with the target object is a + descendant of the transaction associated with the parameter object.

+ + + + is_same_transaction(Coordinator, OtherCoordinator) -> Return + Return true if the transaction associated with the target object is related to the transaction associated with the parameter object + + Coordinator = #objref + OtherCoordinator = #objref + Return = Boolean + + +

Returns true if the transaction associated with the target object is + related to the transaction associated with the parameter object.

+ + + + is_top_level_transaction(Coordinator) -> Return + Return true if the transaction associated with the target object is a top-level transaction + + Coordinator = #objref + Return = Boolean + + +

Returns true if the transaction associated with the target object is + a top-level transaction.

+ + + + register_resource(Coordinator, Resource) -> RecoveryCoordinator + Register the parameter Resourceobject as a participant in the transaction associated with the target object + + Coordinator = #objref + Resource = #objref + RecoveryCoordinator = #objref + + +

This operation registers the parameter Resource object as a participant in the + transaction associated with the target object. The RecoveryCoordinator returned + by this operation can be used by this Resource during recovery.

+ +

The Resources will be called in FIFO-order when preparing or committing. + Hence, be sure to register the Resources in the correct order.

+ +

Raises exception:

+ + 'Inactive' - if target transaction has already been prepared. + + + + + register_subtran_aware(Coordinator, SubtransactionAwareResource) -> Return + Register the parameter SubtransactionAwareResourceobject such that it will be notified when the transaction, associated wit the target object, has committed or rolled back + + Coordinator = #objref + Return = ok + + +

This operation registers the parameter SubtransactionAwareResource object such that + it will be notified when the transaction, associated wit the target object, + has committed or rolled back.

+ +

The Resources will be called in FIFO-order. + Hence, be sure to register the Resources in the correct order.

+ + + + + rollback_only(Coordinator) -> Return + Modify the transaction associated with the target object so the only possible outcome is to rollback the transaction + + Coordinator = #objref + Return = ok + + +

The transaction associated with the target object is modified so the only + possible outcome is to rollback the transaction.

+ + + + + + diff --git a/lib/cosTransactions/doc/src/CosTransactions_RecoveryCoordinator.xml b/lib/cosTransactions/doc/src/CosTransactions_RecoveryCoordinator.xml new file mode 100644 index 0000000000..4b870f4b90 --- /dev/null +++ b/lib/cosTransactions/doc/src/CosTransactions_RecoveryCoordinator.xml @@ -0,0 +1,82 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + CosTransactions_­RecoveryCoordinator + ..._RecoveryCoordinator + Niclas Eklund + Niclas Eklund + + Niclas Eklund + + 1999-04-12 + PA1 +
+ CosTransactions_RecoveryCoordinator + This module implements the OMG CosTransactions::RecoveryCoordinator interface. + +

To get access to the record definitions for the structures use:

+-include_lib("cosTransactions/include/CosTransactions.hrl").

+ + + + replay_completion(RecoveryCoordinator, Timeout, Resource) -> Return + Return the current status of the transaction + + RecoveryCoordinator = #objref + Timeout = integer(), milliseconds | 'infinity' + Resource = #objref + Return = Status | {'EXCEPTION', E} + E = #'CosTransactions_NotPrepared'{} + Status = atom() + + +

The RecoveryCoordinator object is returned by the operation + CosTransactions_Coordinator:register_resource/3. The replay_completion/2 + may only be used by the registered Resource and returns the current status + of the transaction. The operation is used when recovering after a failure.

+

Possible Status replies:

+ + 'StatusCommitted' + 'StatusCommitting' + 'StatusMarkedRollback' + 'StatusRollingBack' + 'StatusRolledBack' + 'StatusActive' + 'StatusPrepared' + 'StatusUnknown' + 'StatusNoTransaction' + 'StatusPreparing' + + +

replay_completion/3 is blocking and may cause dead-lock if a child + calls this function at the same time as its parent invokes an operation + on the child. Dead-lock will not occur if the timeout has any value except 'infinity'.

+

If the call is external incoming (intra-ORB) the timeout will not be activated. + Hence, similar action must be taken if the Resource resides on another vendors ORB.

+ + + + + + + diff --git a/lib/cosTransactions/doc/src/CosTransactions_Resource.xml b/lib/cosTransactions/doc/src/CosTransactions_Resource.xml new file mode 100644 index 0000000000..1f091a5092 --- /dev/null +++ b/lib/cosTransactions/doc/src/CosTransactions_Resource.xml @@ -0,0 +1,128 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + CosTransactions_Resource + + + + 1999-04-12 + PA1 +
+ CosTransactions_Resource + This module implements the OMG CosTransactions::Resource interface. + +

To get access to the record definitions for the structures use:

+-include_lib("cosTransactions/include/CosTransactions.hrl").

+ + + + commit(Resource) -> Return + Instruct the target object to commit the transaction + + Resource = #objref + Return = ok | {'EXCEPTION', E} + E = #'CosTransactions_NotPrepared'{} | #'CosTransactions_HeuristicRollback'{} | #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazard'{} + + +

This operation instructs the Resource to commit all changes made as a part of the transaction.

+

The Resource can raise:

+ + Heuristic Exception - if a Heuristic decision is made which differ + from the true outcome of the transaction. The Resource must remember + the Heuristic outcome until the forget operation is performed. + + + + + commit_one_phase(Resource) -> Return + Instruct the target object to commit the transaction + + Resource = #objref + Return = ok | {'EXCEPTION', E} + E = #'CosTransactions_HeuristicHazard'{} | #'CosTransactions_TransactionRolledBack'{} + + +

If possible, the Resource should commit all changes made as part of the transaction, + else it should raise the TRANSACTION_ROLLEDBACK exception. + This operation can only be used if the Resource is the only child of its parent.

+ + + + forget(Resource) -> Return + Instruct the target object to forget any heuristic decisions + + Resource = #objref + Return = ok + + +

This operation informs the Resource that it is safe to forget any Heuristic + decisions and the knowledge of the transaction.

+ + + + prepare(Resource) -> Return + Instruct the target object to begin the two-phase commit protocol + + Resource = #objref + Return = Vote | {'EXCEPTION', E} + Vote = 'VoteReadOnly' | 'VoteCommit' | 'VoteRollback' + E = #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazard'{} + + +

This operation is invoked on the Resource to begin the two-phase commit protocol.

+

The Resource can reply:

+ + 'VoteReadOnly' - if no persistent data has been modified by the transaction. + The Resource can forget all knowledge of the transaction. + 'VoteCommit' - if the Resource has been prepared and is able to write all the + data needed to commit the transaction to stable storage. + 'VoteRollback' - under any circumstances but must do so if none of the alternatives above + are applicable. + Heuristic Exception - if a Heuristic decision is made which differ + from the true outcome of the transaction. The Resource must remember + the Heuristic outcome until the forget operation is performed. + + + + + rollback(Resource) -> Return + Instruct the target object to rollback the transaction + + Resource = #objref + Return = ok | {'EXCEPTION', E} + E = #'CosTransactions_HeuristicCommit'{} | #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazard'{} + + +

This operation instructs the Resource to rollback all changes made as a part of the transaction.

+

The Resource can raise:

+ + Heuristic Exception - if a Heuristic decision is made which differ + from the true outcome of the transaction. The Resource must remember + the Heuristic outcome until the forget operation is performed. + + + + + + + diff --git a/lib/cosTransactions/doc/src/CosTransactions_SubtransactionAwareResource.xml b/lib/cosTransactions/doc/src/CosTransactions_SubtransactionAwareResource.xml new file mode 100644 index 0000000000..2c7b6b5215 --- /dev/null +++ b/lib/cosTransactions/doc/src/CosTransactions_SubtransactionAwareResource.xml @@ -0,0 +1,75 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + CosTransactions_­SubtransactionAwareResource + ..._SubtransactionAwareResource + + + + 1999-04-12 + PA1 +
+ CosTransactions_SubtransactionAwareResource + This module implements the OMG CosTransactions::SubtransactionAwareResource interface. + +

This interface inherits the CosTransactions::Resource interface. Hence, + it must also support all operations defined in the Resource interface.

+

To get access to the record definitions for the structures use:

+-include_lib("cosTransactions/include/CosTransactions.hrl").

+ + + + commit_subtransaction(SubtransactionAwareResource, Coordinator) -> Return + Notify the target object that the transaction has committed + + SubtransactionAwareResource = #objref + Coordinator = #objref + Return = ok + + +

If the SubtransactionAwareResource have been registered with a subtransaction + using the operation CosTransactions_Coordinator:register_subtran_aware/2, + it will be notified when the transaction has committed.

+ +

The results of a committed subtransaction are relative to the completion of its ancestor + transactions, that is, these results can be undone if any ancestor transaction is rolled back.

+ + + + + rollback_subtransaction(SubtransactionAwareResource) -> Return + Notify the target object that the transaction has been rolled back + + SubtransactionAwareResource = #objref + Return = ok + + +

If the SubtransactionAwareResource have been registered with a transactions + using the operation CosTransactions_Coordinator:register_subtran_aware/2 + it will be notified when the transaction has rolled back.

+ + + + + + diff --git a/lib/cosTransactions/doc/src/CosTransactions_Synchronization.xml b/lib/cosTransactions/doc/src/CosTransactions_Synchronization.xml new file mode 100644 index 0000000000..62d19fe98f --- /dev/null +++ b/lib/cosTransactions/doc/src/CosTransactions_Synchronization.xml @@ -0,0 +1,69 @@ + + + + +
+ + 1999 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + CosTransactions_Synchronization + Niclas Eklund + Niclas Eklund + + Niclas Eklund + + 1999-04-12 + PA1 +
+ CosTransactions_Synchronization + This module implements the OMG CosTransactions::Synchronization interface. + +

To get access to the record definitions for the structures use:

+-include_lib("cosTransactions/CosTransactions.hrl").

+ + + + before_completion(Synchronization) -> Return + Notify the target object that the transaction is about to enter the prepare phase + + Synchronization = #objref + Return = ok + + +

If the target object is a transaction using the operation register_synchronization/2 + it will be notified to perform necessary processing prior to the prepare phase.

+ + + + after_completion(Synchronization) -> Return + Notify the target object that the transaction is completed + + Synchronization = #objref + Return = ok + + +

If the target object is a transaction using the operation register_synchronization/2 + it will be notified to perform necessary processing after terminating the transaction.

+ + + + + + diff --git a/lib/cosTransactions/doc/src/CosTransactions_Terminator.xml b/lib/cosTransactions/doc/src/CosTransactions_Terminator.xml new file mode 100644 index 0000000000..0a8ebe6975 --- /dev/null +++ b/lib/cosTransactions/doc/src/CosTransactions_Terminator.xml @@ -0,0 +1,72 @@ + + + + +
+ + 1999 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + CosTransactions_Terminator + Niclas Eklund + Niclas Eklund + + Niclas Eklund + + 1999-04-12 + PA1 +
+ CosTransactions_Terminator + This module implements the OMG CosTransactions::Terminator interface. + +

To get access to the record definitions for the structures use:

+-include_lib("cosTransactions/include/CosTransactions.hrl").

+ + + + commit(Terminator, ReportHeuristics) -> Return + Try to commit a transaction + + Terminator = #objref + ReportHeuristics = boolean() + Return = ok | {'EXCEPTION', E} + E = #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazrd'{} | #'CosTransactions_TransactionRolledBack'{} + + +

This operation initiates the two-phase commit protocol. If the transaction has not been marked + 'rollback only' and all the participants agree to commit, the operation terminates normally. Otherwise, + the TransactionRolledBack is raised. If the parameter ReportHeuristics is true and inconsistent + outcomes by raising an Heuristic Exception.

+ + + + rollback(Terminator) -> Return + Rollback a transaction + + Terminator = #objref + Return = ok + + +

This operation roles back the transaction.

+ + + + + + diff --git a/lib/cosTransactions/doc/src/CosTransactions_TransactionFactory.xml b/lib/cosTransactions/doc/src/CosTransactions_TransactionFactory.xml new file mode 100644 index 0000000000..181801c574 --- /dev/null +++ b/lib/cosTransactions/doc/src/CosTransactions_TransactionFactory.xml @@ -0,0 +1,64 @@ + + + + +
+ + 1999 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + CosTransactions_­TransactionFactory + ..._TransactionFactory + Niclas Eklund + Niclas Eklund + + Niclas Eklund + + 1999-04-12 + PA1 +
+ CosTransactions_TransactionFactory + This module implements the OMG CosTransactions::TransactionFactory interface. + +

To get access to the record definitions for the structures use:

+-include_lib("cosTransactions/include/CosTransactions.hrl").

+ + + + create(TransactionFactory, Timeout) -> Control + Create a new top-level transaction + + TransactionFactory = #objref + Timeout = integer() + Control = #objref + + +

This operation creates a new top-level transaction.

+

The Timeout argument can be:

+ + 0 - no timeout. + N (integer() > 0) - the transaction will be subject to being rolled back + if it does not complete before N seconds have elapsed. + + + + + + + diff --git a/lib/cosTransactions/doc/src/CosTransactions_TransactionalObject.xml b/lib/cosTransactions/doc/src/CosTransactions_TransactionalObject.xml new file mode 100644 index 0000000000..0e836f5818 --- /dev/null +++ b/lib/cosTransactions/doc/src/CosTransactions_TransactionalObject.xml @@ -0,0 +1,42 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + CosTransactions_TransactionalObject + + + + 1999-04-12 + PA1 +
+ CosTransactions_TransactionalObject + This module implements the OMG CosTransactions::TransactionalObject interface. + +

To get access to the record definitions for the structures use:

+-include_lib("cosTransactions/CosTransactions.hrl").

+

The TransactionalObject interface is used by an object to indicate that it is transactional. + By supporting this interface, an object indicates that it wants the transaction context associated with + the client to be associated with all operation on its interface. No operations are defined.

+ + + + diff --git a/lib/cosTransactions/doc/src/Makefile b/lib/cosTransactions/doc/src/Makefile new file mode 100644 index 0000000000..eab52d3dc9 --- /dev/null +++ b/lib/cosTransactions/doc/src/Makefile @@ -0,0 +1,229 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1999-2009. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% +# +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(COSTRANSACTIONS_VSN) +APPLICATION=cosTransactions + +# ---------------------------------------------------- +# Include dependency +# ---------------------------------------------------- + +ifndef DOCSUPPORT +include make.dep +endif + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_APPLICATION_FILES = ref_man.xml +XML_REF3_FILES = \ + cosTransactions.xml \ + CosTransactions_Control.xml \ + CosTransactions_Coordinator.xml \ + CosTransactions_RecoveryCoordinator.xml \ + CosTransactions_Resource.xml \ + CosTransactions_SubtransactionAwareResource.xml \ + CosTransactions_Terminator.xml \ + CosTransactions_TransactionFactory.xml +# CosTransactions_Synchronization.xml + +XML_PART_FILES = \ + part.xml \ + part_notes.xml +XML_CHAPTER_FILES = \ + ch_contents.xml \ + ch_introduction.xml \ + ch_install.xml \ + ch_example.xml \ + ch_skeletons.xml \ + notes.xml + +BOOK_FILES = book.xml + +TECHNICAL_DESCR_FILES = + +GIF_FILES = \ + book.gif \ + notes.gif \ + ref_man.gif \ + user_guide.gif + +PS_FILES = + +# ---------------------------------------------------- + +INTERNAL_HTML_FILES = $(TECHNICAL_DESCR_FILES:%.xml=$(HTMLDIR)/%.html) + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info +EXTRA_FILES = summary.html.src \ + $(DEFAULT_GIF_FILES) \ + $(DEFAULT_HTML_FILES) \ + $(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html) + +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) + +ifdef DOCSUPPORT + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +else + +TEX_FILES_BOOK = \ + $(BOOK_FILES:%.xml=%.tex) +TEX_FILES_REF_MAN = $(XML_REF3_FILES:%.xml=%.tex) \ + $(XML_APPLICATION_FILES:%.xml=%.tex) +TEX_FILES_USERS_GUIDE = \ + $(XML_CHAPTER_FILES:%.xml=%.tex) + +TOP_PDF_FILE = $(APPLICATION)-$(VSN).pdf + +TOP_PS_FILE = $(APPLICATION)-$(VSN).ps + +$(TOP_PDF_FILE): book.dvi ../../vsn.mk + $(DVI2PS) $(DVIPS_FLAGS) -f $< | $(DISTILL) $(DISTILL_FLAGS) > $@ + +$(TOP_PS_FILE): book.dvi ../../vsn.mk + $(DVI2PS) $(DVIPS_FLAGS) -f $< > $@ + +endif + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += +DVIPS_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +ifdef DOCSUPPORT + +docs: pdf html man + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +else + +ifeq ($(DOCTYPE),pdf) +docs: pdf +else +ifeq ($(DOCTYPE),ps) +docs: ps +else +docs: html gifs man +endif +endif + +pdf: $(TOP_PDF_FILE) + +ps: $(TOP_PS_FILE) + +html: $(HTML_FILES) $(INTERNAL_HTML_FILES) + +clean clean_docs clean_tex: + rm -f $(TEX_FILES_USERS_GUIDE) $(TEX_FILES_REF_MAN) $(TEX_FILES_BOOK) + rm -f $(HTML_FILES) $(MAN3_FILES) + rm -f $(TOP_PDF_FILE) $(TOP_PS_FILE) + rm -f errs core *~ *xmls_output *xmls_errs $(LATEX_CLEAN) + +endif + +man: $(MAN3_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +$(INDEX_TARGET): $(INDEX_SRC) + sed -e 's;%VSN%;$(VSN);' $(INDEX_SRC) > $(INDEX_TARGET) + +debug opt: + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +ifdef DOCSUPPORT + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 +else + +ifeq ($(DOCTYPE),pdf) +release_docs_spec: pdf + $(INSTALL_DIR) $(RELEASE_PATH)/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELEASE_PATH)/pdf +else +ifeq ($(DOCTYPE),ps) +release_docs_spec: ps + $(INSTALL_DIR) $(RELEASE_PATH)/ps + $(INSTALL_DATA) $(TOP_PS_FILE) $(RELEASE_PATH)/ps +else +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(GIF_FILES) $(EXTRA_FILES) $(HTML_FILES) \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3 + +endif +endif + +endif + +release_spec: + diff --git a/lib/cosTransactions/doc/src/book.gif b/lib/cosTransactions/doc/src/book.gif new file mode 100644 index 0000000000..94b3868792 Binary files /dev/null and b/lib/cosTransactions/doc/src/book.gif differ diff --git a/lib/cosTransactions/doc/src/book.xml b/lib/cosTransactions/doc/src/book.xml new file mode 100644 index 0000000000..785cf387c0 --- /dev/null +++ b/lib/cosTransactions/doc/src/book.xml @@ -0,0 +1,48 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + cosTransactions + Niclas Eklund + + 1999-04-14 + 2.0 +
+ + + cosTransactions + + + + + + + + + + + + + + + + diff --git a/lib/cosTransactions/doc/src/ch_contents.xml b/lib/cosTransactions/doc/src/ch_contents.xml new file mode 100644 index 0000000000..21cefda955 --- /dev/null +++ b/lib/cosTransactions/doc/src/ch_contents.xml @@ -0,0 +1,74 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + The cosTransactions Application + Niclas Eklund + + 1999-04-14 + B + ch_contents.xml +
+ +
+ Content Overview +

The cosTransactions documentation is divided into three sections: +

+ + +

PART ONE - The User's Guide +

+Description of the cosTransactions Application including + services and a small tutorial demonstrating + the development of a simple service.

+ + +

PART TWO - Release Notes +

+A concise history of cosTransactions.

+ + +

PART THREE - The Reference Manual +

+ A quick reference guide, including a + brief description, to all the functions available in cosTransactions.

+ + +
+ +
+ Brief Description of the User's Guide +

The User's Guide contains the following parts:

+ + +

cosTransactions overview

+ + +

cosTransactions installation

+ + +

A tutorial example

+ + +
+ + diff --git a/lib/cosTransactions/doc/src/ch_example.xml b/lib/cosTransactions/doc/src/ch_example.xml new file mode 100644 index 0000000000..65350166f0 --- /dev/null +++ b/lib/cosTransactions/doc/src/ch_example.xml @@ -0,0 +1,280 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + cosTransactions Examples + + + 1999-04-27 + A + ch_example.xml +
+ +
+ A Tutorial on How to Create a Simple Service + +
+ Interface design +

To use the cosTransactions application participants must be implemented. + There are two types of participants:

+ + CosTransactions_Resource - operations used to commit or rollback resources. + CosTransactions_SubtransactionAwareResource - + operations used when the resources want to be notified when a subtransaction commits. + This interface inherits the CosTransactions_Resource + +

The interfaces for these participants are defined in CosTransactions.idl

+
+ +
+ Generating a Participant Interface +

We start by creating an interface which inherits from CosTransactions::Resource. Hence, + we must also implement all operations defined in the Resource interface. The IDL-file could look like:

+ + +module ownResourceImpl { + + interface ownInterface:CosTransactions::Resource { + + void ownFunctions(in any NeededArguments) + raises(Systemexceptions,OwnExceptions); + + }; +}; + +#endif + ]]> +

Run the IDL compiler on this file by calling the ic:gen/1 function. + This will produce the API named ownResourceImpl_ownInterface.erl. + After generating the API stubs and the server skeletons it is time to + implement the servers and if no special options are sent + to the IDl compiler the file name is ownResourceImpl_ownInterface_impl.erl.

+
+ +
+ Implementation of Participant interface +

If the participant is intended to be a plain Resource, we must implement the following operations:

+ + prepare/1 - this operation is invoked on the Resource to begin the two-phase commit protocol. + rollback/1 - this operation instructs the Resource to rollback all changes made as a part of the transaction. + commit/1 - this operation instructs the Resource to commit all changes made as a part of the transaction. + commit_one_phase/1 - if possible, the Resource should commit all changes made as part of the transaction. + This operation can only be used if the Resource is the only child of its parent. + forget/1 - this operation informs the Resource that it is safe to forget any + Heuristic decisions is a unilateral decision by a participant to commit or rollback without receiving the true outcome of the transaction from its parents coordinator.and the knowledge of the transaction. + ownFunctions - all application specific operations. + +

If the participant wants to be notified when a subtransaction commits, we must also implement the following operations + (besides the operations above):

+ + commit_subtransaction/2 - if the SubtransactionAwareResource have been registered + with a transactions using the operation CosTransactions_Coordinator:register_subtran_aware/2 it will + be notified when the transaction has + committed. + rollback_subtransaction/1 - if the SubtransactionAwareResource have been registered + with a transactions using the operation CosTransactions_Coordinator:register_subtran_aware/2 + it will be notified when the transaction has + rolled back. + + +

The results of a committed subtransaction are relative to the completion of its ancestor transactions, + that is, these results can be undone if any ancestor transaction is rolled back.

+ +
+ +
+ Participant Operations Behavior +

Each application participant must behave in a certain way to ensure that the two-phase commit protocol + can complete the transactions correctly.

+ +
+ prepare +

This operation ask the participant to vote on the outcome of the transaction. Possible replies are:

+ + 'VoteReadOnly' - if no data associated with the transaction has been modified VoteReadOnly may be returned. + The Resource can forget all knowledge of the transaction and terminate. + 'VoteCommit' - if the Resource is able to write all the data needed to commit the transaction to a stable storage, + VoteCommit may be returned. The Resource will then wait until it is informed of the outcome of the transaction. + The Resource may, however, make a unilateral decision (Heuristic) to commit or rollback changes associated + with the transaction. When the Resource is informed of the true outcome (rollback/commit) and it is equal to + the Heuristic decision the Resource just return 'ok'. But, if there is a mismatch and the commit-operation is irreversible, + the Resource must raise a Heuristic Exception and wait + until the forget operation is invoked. The Heuristic Decision must be recorded in stable storage. + 'VoteRollback' - the Resource may vote VoteRollback under any circumstances. + The Resource can forget all knowledge of the transaction and terminate. + + +

Before replying to the prepare operation, the Resource must record the prepare state, the reference of its + superior RecoveryCoordinator in stable storage. + The RecoveryCoordinator is obtained when registering as a participant in a transaction.

+ +
+ +
+ rollback +

The Resource should, if necessary, rollback all changes made as part of the transaction. If the Resource is not aware of the + transaction it should do nothing, e.g., recovered after a failure and have no data in stable storage. Heuristic Decisions + must be handled as described above.

+
+ +
+ commit +

The Resource should, if necessary, commit all changes made as part of the transaction. If the Resource is not aware of the + transaction it should do nothing, e.g., recovered after a failure and have no data in stable storage. Heuristic Decisions + must be handled as described above.

+
+ +
+ commit_one_phase +

If possible, the Resource should commit all changes made as part of the transaction. If it cannot, it should raise the + TRANSACTION_ROLLEDBACK exception. This operation can only be used if the Resource is the only child of its parent. + If a failure occurs the completion of the operation must be retried when the failure is repaired. Heuristic Decisions + must be handled as described above.

+
+ +
+ forget +

If the Resource raised a Heuristic Exception to commit, rollback or commit_one_phase this operation + will be performed. The Resource can forget all knowledge of the transaction and terminate.

+
+ +
+ commit_subtransaction +

If the SubtransactionAwareResource have been registered with a subtransaction + using the operation CosTransactions_Coordinator:register_subtran_aware/2 + it will be notified when the transaction has committed. The Resource may raise the exception + 'TRANSACTION_ROLLEDBACK'.

+ +

The result of a committed subtransaction is relative to the completion of its ancestor + transactions, that is, these results can be undone if any ancestor transaction is rolled back.

+ +
+ +
+ rollback_subtransaction +

If the SubtransactionAwareResource have been registered with a subtransaction + using the operation CosTransactions_Coordinator:register_subtran_aware/2 + it will be notified when the subtransaction has rolled back.

+
+
+ +
+ How to Run Everything +

Below is a short transcript on how to run cosTransactions.

+ + +%% Start Mnesia and Orber +mnesia:delete_schema([node()]), +mnesia:create_schema([node()]), +orber:install([node()]), +application:start(mnesia), +application:start(orber), + +%% Register CosTransactions in the IFR. +'oe_CosTransactions':'oe_register'(), + +%% Register the application specific Resource implementations +%% in the IFR. +'oe_ownResourceImpl':'oe_register'(), + +%%-- Set parameters -- +%% Timeout can be either 0 (no timeout) or an integer N > 0. +%% The later state that the transaction should be rolled +%% back if the transaction have not completed within N seconds. +TimeOut = 0, + +%% Do we want the transaction to report Heuristic Exceptions? +%% This variable must be boolean and indicates the way the +%% Terminator should behave. +Heuristics = true, + +%% Start the cosTransactions application. +cosTransactions:start(), %% or application:start(cosTransactions), + +%% Start a factory using the default configuration +TrFac = cosTransactions:start_factory(), +%% ... or use configuration parameters. +TrFac = cosTransactions:start_factory([{typecheck, false}, {hash_max, 3013}]), + +%% Create a new top-level transaction. +Control = 'CosTransactions_TransactionFactory':create(TrFac, TimeOut), + +%% Retrieve the Coordinator and Terminator object references from +%% the Control Object. +Term = 'CosTransactions_Control':get_terminator(Control), +Coord = 'CosTransactions_Control':get_coordinator(Control), + +%% Create two SubTransactions with the root-Coordinator as parent. +SubCont1 = 'CosTransactions_Coordinator':create_subtransaction(Coord), +SubCont2 = 'CosTransactions_Coordinator':create_subtransaction(Coord), + +%% Retrieve the Coordinator references from the Control Objects. +SubCoord1 = 'CosTransactions_Control':get_coordinator(SubCont1), +SubCoord2 = 'CosTransactions_Control':get_coordinator(SubCont2), + +%% Create application Resources. We can, for example, start the Resources +%% our selves or look them up in the naming service. This is application +%% specific. +Res1 = ... +Res2 = ... +Res3 = ... +Res4 = ... + +%% Register Resources with respective Coordinator. Each call returns +%% a RecoveryCoordinator object reference. +RC1 = 'CosTransactions_Coordinator':register_resource(SubCoord1, Res1), +RC2 = 'CosTransactions_Coordinator':register_resource(SubCoord1, Res2), +RC3 = 'CosTransactions_Coordinator':register_resource(SubCoord2, Res3), +RC4 = 'CosTransactions_Coordinator':register_resource(SubCoord2, Res4), + +%% Register Resource 4 with SubCoordinator 1 so that the Resource will be +%% informed when the SubCoordinator commits or roll-back. +'CosTransactions_Coordinator':register_subtran_aware(SubCoord1, Res4), + +%% We are now ready to try to commit the transaction. The second argument +%% must be a boolean +Outcome = (catch 'CosTransactions_Terminator':commit(Term, Heuristics)), + + +

For the cosTransaction application to be able to recognize if a Resource is + dead or in the process of restarting the Resource must be started as persistent, + e.g., 'OwnResource':oe_create_link(Env, [{regname, {global, RegName}}, {persistent, true}]). + For more information see the Orber documentation.

+ +

The outcome of the transaction can be:

+ + ok - the transaction was successfully committed. + {'EXCEPTION', HeuristicExc} - at least one participant made a + Heuristic decision or, due to a failure, one or more participants + where unreachable. + {'EXCEPTION', #'TRANSACTION_ROLLEDBACK'{}} - + the transaction was successfully rolled back. + Any system exception - + the transaction failed with unknown reason. + +
+
+ + diff --git a/lib/cosTransactions/doc/src/ch_install.xml b/lib/cosTransactions/doc/src/ch_install.xml new file mode 100644 index 0000000000..d4b64d3987 --- /dev/null +++ b/lib/cosTransactions/doc/src/ch_install.xml @@ -0,0 +1,103 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Installing cosTransactions + + + 1999-04-20 + + ch_install.xml +
+ +
+ Installation Process +

This chapter describes how to install + cosTransactions + in an Erlang Environment. +

+ +
+ Preparation +

Before starting the installation process for cosTransactions, + the application Orber must be running.

+

The cosTransactions application must be able to log progress to disk. The log files are + created in the current directory as "oe_name@machine_type_timestamp". Hence, read and + write rights must be granted. If the transaction completes in an orderly fashion the + logfiles are removed, but not if an error, which demands human intervention, occur.

+
+ +
+ Configuration +

When using the Transaction Service the cosTransactions application + must be started using either cosTransactions:start() or + application:start(cosTransactions). +

+

The following application configuration parameters exist:

+ + maxRetries - default is 40 times, i.e., if a transaction participant is unreachable + the application will retry to contact it N times. Reaching the maximum is considered to be a disaster. + comFailWait - default is 5000 milliseconds, i.e., before the application + retries to contact unreachable transaction participants the application wait Time milliseconds. + +

Then the Transaction Factory + must be started:

+ + cosTransactions:start_factory() - starts and returns a reference to a factory using default configuration parameters. + cosTransactions:start_factory(Options) - starts and returns a reference to a factory using given configuration parameters. + +

The following options exist: +

+ + {hash_max, HashValue} - + This value denotes the upper bound of the hash value the Coordinator uses. + Default is 1013. HashValue must be an integer. + {allow_subtr, Boolean} - + If set to true it is possible to create subtransactions. + Default is true. + {typecheck, Boolean} - + If set to to true all transaction operation's arguments will be type-checked. + Default is true. + {tty, Boolean} - + Enables or disables error printouts to the tty. + If Flag is false, all text that the error logger would have sent to the terminal is discarded. + If Flag is true, error messages are sent to the terminal screen. + {logfile, FileName} - + This function makes it possible to store all system information in FileName (string()). + It can be used in combination with the tty(false) item to have a silent system, + where all system information are logged to a file. + As default no logfile is used. + {maxRetries, Integer} - + default is 40 times, i.e., if a transaction participant is unreachable the application will + retry to contact it N times. Reaching the maximum is considered to be a disaster. + This option overrides the application configuration parameter. + {comFailWait, Integer} - + default is 5000 milliseconds, i.e., before the application retries to contact unreachable + transaction participants the application wait Time milliseconds. + This option overrides the application configuration parameter. + +

The Factory is now ready to use. For a more detailed description see Examples. +

+
+
+ + diff --git a/lib/cosTransactions/doc/src/ch_introduction.xml b/lib/cosTransactions/doc/src/ch_introduction.xml new file mode 100644 index 0000000000..b0e58c5528 --- /dev/null +++ b/lib/cosTransactions/doc/src/ch_introduction.xml @@ -0,0 +1,64 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Introduction to cosTransactions + Niclas Eklund + + 1999-04-26 + + ch_introduction.xml +
+ +
+ Overview +

The cosTransactions application is a Transaction Service compliant with the OMG + Transaction Service CosTransactions 1.1. +

+ +
+ Purpose and Dependencies +

cosTransactions is dependent on Orber version 3.0.1 or later(see the Orber + documentation), which provides CORBA functionality in an Erlang environment.

+

cosTransactions is dependent on supervisor/stdlib-1.7 or later.

+

Basically, cosTransaction implements a two-phase commit protocol and allows objects running + on different platforms to participate in a transaction.

+
+ +
+ Prerequisites +

To fully understand the concepts presented in the + documentation, it is recommended that the user is familiar + with distributed programming, CORBA and the Orber application. +

+

Recommended reading includes CORBA, Fundamentals and Programming - Jon Siegel and Open Telecom Platform Documentation Set. It is also helpful to have read + Concurrent Programming in Erlang and, for example, Transaction Processing: concepts and techniques - Jim Gray, Andreas Reuter.

+ +

The cosTransaction application is compliant with the OMG CosTransactions specification 1.1. Using + other vendors transaction service, compliant with the OMG CosTransactions specification 1.0, may + not work since the 'TRANSACTION_REQUIRED', 'TRANSACTION_ROLLEDBACK' and 'INVALID_TRANSACTION' + exceptions have been redefined to be system exceptions, i.e., used to be transaction-specific ('CosTransactions_Exc').

+ +
+
+ + diff --git a/lib/cosTransactions/doc/src/ch_skeletons.xml b/lib/cosTransactions/doc/src/ch_skeletons.xml new file mode 100644 index 0000000000..a6dd41f929 --- /dev/null +++ b/lib/cosTransactions/doc/src/ch_skeletons.xml @@ -0,0 +1,213 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Resource Skeletons + Niclas Eklund + + 1999-04-29 + + ch_skeletons.xml +
+ +
+ Resource Skeletons +

This chapter provides a skeleton for application Resources. For more information + see the Orber documentation.

+ +%%%----------------------------------------------------------- +%%% File : Module_Interface_impl.erl +%%% Author : +%%% Purpose : +%%% Created : +%%%----------------------------------------------------------- + +-module('Module_Interface_impl'). + +%%--------------- INCLUDES ----------------------------------- +-include_lib("orber/include/corba.hrl"). +-include_lib("cosTransactions/include/CosTransactions.hrl"). + +%%--------------- EXPORTS------------------------------------- +%%- Inherit from CosTransactions::Resource ------------------- +-export([prepare/2, + rollback/2, + commit/2, + commit_one_phase/2, + forget/2]). + +%%- Inherit from CosTransactions::SubtransactionAwareResource +-export([commit_subtransaction/3, + rollback_subtransaction/2]). + +%%--------------- gen_server specific ------------------------ +-export([init/1, terminate/2, code_change/3, handle_info/2]). + +%%------------------------------------------------------------ +%% function : gen_server specific +%%------------------------------------------------------------ +init(Env) -> + %% 'trap_exit' optional + process_flag(trap_exit,true), + + %%--- Possible replies --- + %% Reply and await next request + {ok, State}. + + %% Reply and if no more requests within Time the special + %% timeout message should be handled in the + %% Module_Interface_impl:handle_info/2 call-back function (use the + %% IC option {{handle_info, "Module::Interface"}, true}). + {ok, State, TimeOut}. + + %% Return ignore in order to inform the parent, especially if it is a + %% supervisor, that the server, as an example, did not start in + %% accordance with the configuration data. + ignore. + + %% If the initializing procedure fails, the reason + %% is supplied as StopReason. + {stop, StopReason}. + + +terminate(Reason, State) -> + ok. + +code_change(OldVsn, State, Extra) -> + {ok, NewState}. + +%% If use IC option {{handle_info, "Module::Interface"}, true} +handle_info(Info, State) -> + %%--- Possible replies --- + %% Await the next invocation. + {noreply, State}. + %% Stop with Reason. + {stop, Reason, State}. + + +%%- Inherit from CosTransactions::Resource ------------------- +prepare(State) -> + + %%% Do application specific actions here %%% + + %%-- Reply: -- + %% If no data related to the transaction changed. + {reply, 'VoteReadOnly', State} + %% .. or (for example): + {stop, normal, 'VoteReadOnly', State}. + + %% If able to commit + {reply, 'VoteCommit', State} + + %% If not able to commit + {reply, 'VoteRollback', State} + %% .. or (for example): + {stop, normal, 'VoteRollback', State}. + +rollback(State) -> + + %%% Do application specific actions here %%% + + %%-- Reply: -- + %% If able to rollback successfully + {reply, ok, State} + %% .. or (for example): + {stop, normal, ok, State}. + + %% If Heuristic Decision. Raise exception: + corba:raise(#'CosTransactions_HeuristicMixed' {}) + corba:raise(#'CosTransactions_HeuristicHazard' {}) + corba:raise(#'CosTransactions_HeuristicCommit'{}) + + +commit(State) -> + + %%% Do application specific actions here %%% + + %%-- Reply: -- + %% If able to commit successfully + {reply, ok, State} + %% .. or (for example): + {stop, normal, ok, State}. + + %% If the prepare operation never been invoked: + corba:raise(#'CosTransactions_NotPrepared'{}) + + %% If Heuristic Decision. Raise exception: + corba:raise(#'CosTransactions_HeuristicMixed' {}) + corba:raise(#'CosTransactions_HeuristicHazard' {}) + corba:raise(#'CosTransactions_HeuristicRollback'{}) + + +commit_one_phase(State) -> + + %%% Do application specific actions here %%% + + %%-- Reply: -- + %% If able to commit successfully + {reply, ok, State} + %% .. or (for example): + {stop, normal, ok, State}. + + %% If fails. Raise exception: + corba:raise(#'CosTransactions_HeuristicHazard' {}) + + %% If able to rollback successfully + corba:raise(#'CosTransactions_TransactionRolledBack' {}) + + +forget(State) -> + + %%% Do application specific actions here %%% + + %%-- Reply: -- + {reply, ok, State}. + %% .. or (for example): + {stop, normal, ok, State}. + + + +%%%%%% If the Resource is also supposed to be a %%%%%% +%%%%%% SubtransactionAwareResource implement these. %%%%%% + +%%- Inherit from CosTransactions::SubtransactionAwareResource +commit_subtransaction(State, Parent) -> + %%% Do application specific actions here %%% + + %%-- Reply: -- + {reply, ok, State}. + %% .. or (for example): + {stop, normal, ok, State}. + +rollback_subtransaction(State) -> + %%% Do application specific actions here %%% + + %%-- Reply: -- + {reply, ok, State}. + %% .. or (for example): + {stop, normal, ok, State}. + +%%--------------- END OF MODULE ------------------------------ + +
+ + diff --git a/lib/cosTransactions/doc/src/cosTransactions.xml b/lib/cosTransactions/doc/src/cosTransactions.xml new file mode 100644 index 0000000000..836506974c --- /dev/null +++ b/lib/cosTransactions/doc/src/cosTransactions.xml @@ -0,0 +1,141 @@ + + + + +
+ + 1999 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + cosTransactions + Niclas Eklund + Niclas Eklund + + Niclas Eklund + + 1999-04-23 + PA1 +
+ cosTransactions + The main module of the cosTransactions application. + +

To get access to the record definitions for the structures use:

+-include_lib("cosTransactions/include/CosTransactions.hrl").

+

This module contains the functions for starting and stopping the application. + If the application is started using application:start(cosTransactions) the + default configuration is used (see listing below). The Factory reference is stored using the CosNaming Service + under the id "oe_cosTransactionsFac_IPNo".

+

The following application configuration parameters exist:

+ + maxRetries - default is 40 times, i.e., if a transaction participant is unreachable + the application will retry to contact it N times. Reaching the maximum is considered to be a disaster. + comFailWait - default is 5000 milliseconds, i.e., before the application + retries to contact unreachable transaction participants the application wait Time milliseconds. + + + + + start() -> Return + Start the cosTransactions application + + Return = ok | {error, Reason} + + +

This operation starts the cosTransactions application.

+ + + + stop() -> Return + Stop the cosTransactions application + + Return = ok | {error, Reason} + + +

This operation stops the cosTransactions application.

+ + + + start_factory() -> TransactionFactory + Start a Transaction Factory + + TransactionFactory = #objref + + +

This operation creates a Transaction Factory. + The Factory is used to create a new top-level transaction using default options (see listing below).

+ + + + start_factory(FacDef) -> TransactionFactory + Start a Transaction Factorywith given options + + FacDef = [Options], see Option listing below. + TransactionFactory = #objref + + +

This operation creates a Transaction Factory. + The Factory is used to create a new top-level transaction.

+

The FacDef list must be a list of {Item, Value} tuples, + where the following values are allowed:

+ + {hash_max, HashValue} - + This value denotes the upper bound of the hash value the + Coordinator uses. + Default is 1013. HashValue must be an integer. + {allow_subtr, Boolean} - + If set to true it is possible to create subtransactions. + Default is true. + {typecheck, Boolean} - + If set to to true all transaction operation's arguments will be type-checked. + Default is true. + {tty, Boolean} - + Enables or disables error printouts to the tty. + If Flag is false, all text that the error logger would have sent to the terminal is discarded. + If Flag is true, error messages are sent to the terminal screen. + {logfile, FileName} - + This function makes it possible to store all system information in FileName (string()). + It can be used in combination with the tty(false) item in to have a silent system, + where all system information are logged to a file. + As default no logfile is used. + {maxRetries, Integer} - + default is 40 times, i.e., if a transaction participant is unreachable the application will + retry to contact it N times. Reaching the maximum is considered to be a disaster. + This option overrides the application configuration parameter. + {comFailWait, Integer} - + default is 5000 milliseconds, i.e., before the application retries to contact unreachable + transaction participants the application wait Time milliseconds. + This option overrides the application configuration parameter. + + + + + stop_factory(TransactionFactory) -> Reply + Terminate the target object + + TransactionFactory = #objref + Reply = ok | {'EXCEPTION', E} + + +

This operation stop the target transaction factory.

+ + + + + + diff --git a/lib/cosTransactions/doc/src/fascicules.xml b/lib/cosTransactions/doc/src/fascicules.xml new file mode 100644 index 0000000000..0678195e07 --- /dev/null +++ b/lib/cosTransactions/doc/src/fascicules.xml @@ -0,0 +1,18 @@ + + + + + + User's Guide + + + Reference Manual + + + Release Notes + + + Off-Print + + + diff --git a/lib/cosTransactions/doc/src/make.dep b/lib/cosTransactions/doc/src/make.dep new file mode 100644 index 0000000000..bd45aea286 --- /dev/null +++ b/lib/cosTransactions/doc/src/make.dep @@ -0,0 +1,27 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: CosTransactions_Control.tex CosTransactions_Coordinator.tex \ + CosTransactions_RecoveryCoordinator.tex CosTransactions_Resource.tex \ + CosTransactions_SubtransactionAwareResource.tex \ + CosTransactions_Terminator.tex CosTransactions_TransactionFactory.tex \ + book.tex ch_contents.tex ch_example.tex ch_install.tex \ + ch_introduction.tex ch_skeletons.tex cosTransactions.tex \ + part.tex ref_man.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: ref_man.xml + +ch_example.tex: ../../../../system/doc/definitions/term.defs + diff --git a/lib/cosTransactions/doc/src/notes.gif b/lib/cosTransactions/doc/src/notes.gif new file mode 100644 index 0000000000..e000cca26a Binary files /dev/null and b/lib/cosTransactions/doc/src/notes.gif differ diff --git a/lib/cosTransactions/doc/src/notes.xml b/lib/cosTransactions/doc/src/notes.xml new file mode 100644 index 0000000000..953382ef87 --- /dev/null +++ b/lib/cosTransactions/doc/src/notes.xml @@ -0,0 +1,243 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + cosTransactions Release Notes + Niclas Eklund + Niclas Eklund + + + + 99-04-14 + A + notes.xml +
+ +
+ cosTransactions 1.2.8 + +
+ Improvements and New Features + + +

+ The documentation is now built with open source tools (xsltproc and fop) + that exists on most platforms. One visible change is that the frames are removed.

+

+ Own Id: OTP-8201 Aux Id:

+ + +
+
+ +
+ cosTransactions 1.2.7 + +
+ Improvements and New Features + + +

Obsolete guards, e.g. record vs is_record, has been changed + to avoid compiler warnings.

+

Own id: OTP-7987

+ + +
+
+ +
+ cosTransactions 1.2.6 + +
+ Improvements and New Features + + +

Updated file headers.

+

Own id: OTP-7837

+ + +
+
+ +
+ cosTransactions 1.2.5 + +
+ Improvements and New Features + + +

Documentation source included in open source releases.

+

Own id: OTP-7595

+ + +
+
+ +
+ cosTransactions 1.2.4 + +
+ Improvements and New Features + + +

Updated file headers.

+

Own id: OTP-7011

+ + +
+
+ +
+ cosTransactions 1.2.3 + +
+ Improvements and New Features + + +

The documentation source has been converted from SGML to XML.

+

Own id: OTP-6754 Aux Id:

+ + +
+
+ +
+ cosTransactions 1.2.2 + +
+ Improvements and New Features + + +

Minor Makefile changes.

+

Own id: OTP-6701 Aux Id:

+ + +
+
+ +
+ cosTransactions 1.2.1 + +
+ Improvements and New Features + + +

Removed some unused code.

+

Own id: OTP-6527 Aux Id:

+ + +
+
+ +
+ cosTransactions 1.2 + +
+ Improvements and New Features + + +

The stub/skeleton-files generated by IC have been improved, + i.e., depending on the IDL-files, reduced the size of the + erl- and beam-files and decreased dependencies off Orber's + Interface Repository. It is necessary to re-compile all IDL-files + and use COS-applications, including Orber, compiled with + IC-4.2.

+

Own id: OTP-4576

+ + +
+
+ +
+ cosTransactions 1.1.2 + +
+ Improvements and New Features + + +

To avoid un-necessary Heuristic decisions cosTransactions now + recognize more systems exceptions.

+

Own Id: OTP-4485

+ + +
+
+ +
+ cosTransactions 1.1.1.1 + +
+ Improvements and New Features + + +

Updated internal documentation.

+ + +
+
+ +
+ cosTransactions 1.1.1 + +
+ Improvements and New Features + + +

cosTransactions is now able to handle upgrade properly.

+

Own Id: -

+ + +

The cosTransactions factory now accepts maxRetries and + comFailWait options, which overrides the configuration parameters.

+

Own Id: -

+ + +
+ +
+ Incompatibilities + + +

The configuration parameters comm_failure_wait and max_retries + changed to maxRetries and comFailWait. The default value for + maxRetries have been raised from 20 to 40.

+

Own Id: -

+ + +
+
+ +
+ cosTransactions 1.1 + +
+ Improvements and New Features + + +

First release of the cosTransactions application.

+

Own Id: OTP-1741

+ + +
+
+ + diff --git a/lib/cosTransactions/doc/src/part.xml b/lib/cosTransactions/doc/src/part.xml new file mode 100644 index 0000000000..b5a8397525 --- /dev/null +++ b/lib/cosTransactions/doc/src/part.xml @@ -0,0 +1,40 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + cosTransactions User's Guide + Niclas Eklund + + 1999-04-20 + 2.2 +
+ +

The cosTransactions application is an Erlang implementation + of the OMG CORBA Transaction Service.

+ + + + + + + + diff --git a/lib/cosTransactions/doc/src/part_notes.xml b/lib/cosTransactions/doc/src/part_notes.xml new file mode 100644 index 0000000000..16e1968093 --- /dev/null +++ b/lib/cosTransactions/doc/src/part_notes.xml @@ -0,0 +1,36 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + cosTransactions Release Notes + + + 1999-04-14 + 2.0 +
+ +

The cosTransactions Application is an Erlang implementation of the OMG + CORBA Transaction Service.

+ + + + diff --git a/lib/cosTransactions/doc/src/ref_man.gif b/lib/cosTransactions/doc/src/ref_man.gif new file mode 100644 index 0000000000..b13c4efd53 Binary files /dev/null and b/lib/cosTransactions/doc/src/ref_man.gif differ diff --git a/lib/cosTransactions/doc/src/ref_man.xml b/lib/cosTransactions/doc/src/ref_man.xml new file mode 100644 index 0000000000..b662f30b28 --- /dev/null +++ b/lib/cosTransactions/doc/src/ref_man.xml @@ -0,0 +1,43 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + cosTransactions Reference Manual + Niclas Eklund + + 1999-04-14 + 2.0 +
+ +

The cosTransactions application is an Erlang implementation + of the OMG CORBA Transaction Service.

+ + + + + + + + + + + diff --git a/lib/cosTransactions/doc/src/summary.html.src b/lib/cosTransactions/doc/src/summary.html.src new file mode 100644 index 0000000000..8fb7d6ea20 --- /dev/null +++ b/lib/cosTransactions/doc/src/summary.html.src @@ -0,0 +1 @@ +Orber OMG Transaction Service \ No newline at end of file diff --git a/lib/cosTransactions/doc/src/user_guide.gif b/lib/cosTransactions/doc/src/user_guide.gif new file mode 100644 index 0000000000..e6275a803d Binary files /dev/null and b/lib/cosTransactions/doc/src/user_guide.gif differ -- cgit v1.2.3