diff options
Diffstat (limited to 'lib/cosTransactions/doc')
32 files changed, 2394 insertions, 0 deletions
diff --git a/lib/cosTransactions/doc/html/.gitignore b/lib/cosTransactions/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/cosTransactions/doc/html/.gitignore diff --git a/lib/cosTransactions/doc/man3/.gitignore b/lib/cosTransactions/doc/man3/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/cosTransactions/doc/man3/.gitignore diff --git a/lib/cosTransactions/doc/man6/.gitignore b/lib/cosTransactions/doc/man6/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/cosTransactions/doc/man6/.gitignore diff --git a/lib/cosTransactions/doc/pdf/.gitignore b/lib/cosTransactions/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/cosTransactions/doc/pdf/.gitignore 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year> + <year>2007</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + 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. + </legalnotice> + + <title>CosTransactions_Control</title> + <prepared>Niclas Eklund</prepared> + <responsible>Niclas Eklund</responsible> + <docno></docno> + <approved>Niclas Eklund</approved> + <checked></checked> + <date>1999-04-12</date> + <rev>PA1</rev> + </header> + <module>CosTransactions_Control</module> + <modulesummary>This module implements the OMG CosTransactions::Control interface.</modulesummary> + <description> + <p>To get access to the record definitions for the structures use: <br></br> +<c>-include_lib("cosTransactions/include/CosTransactions.hrl").</c></p> + </description> + <funcs> + <func> + <name>get_coordinator(Control) -> Return</name> + <fsummary>Return the Coordinator object associated with the target object</fsummary> + <type> + <v>Control = #objref</v> + <v>Return = Coordinator | {'EXCEPTION', E}</v> + <v>Coordinator = #objref</v> + <v>E = #'CosTransactions_Unavailable' {}</v> + </type> + <desc> + <p>This operation returns the Coordinator object associated with the target object. + The Coordinator supports operations for termination of a transaction.</p> + </desc> + </func> + <func> + <name>get_terminator(Control) -> Return</name> + <fsummary>Return the Terminator object associated with the target object</fsummary> + <type> + <v>Control = #objref</v> + <v>Return = Terminator | {'EXCEPTION', E}</v> + <v>Terminator = #objref</v> + <v>E = #'CosTransactions_Unavailable' {}</v> + </type> + <desc> + <p>This operation returns the Terminator object associated with the target object. + The Terminator supports operations for termination of a transaction.</p> + </desc> + </func> + </funcs> + +</erlref> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>CosTransactions_Coordinator</title> + <prepared></prepared> + <docno></docno> + <checked></checked> + <date>1999-04-12</date> + <rev>PA1</rev> + </header> + <module>CosTransactions_Coordinator</module> + <modulesummary>This module implements the OMG CosTransactions::Coordinator interface.</modulesummary> + <description> + <p>To get access to the record definitions for the structures use: <br></br> +<c>-include_lib("cosTransactions/include/CosTransactions.hrl").</c></p> + </description> + <funcs> + <func> + <name>create_subtransaction(Coordinator) -> Control</name> + <fsummary>Create a new subtransaction.</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Control = #objref</v> + </type> + <desc> + <p>A new subtransaction is created whose parent is the Coordinator argument.</p> + <p>Raises exception:</p> + <list type="bulleted"> + <item>'SubtransactionsUnavailable' - if nested transactions are not supported.</item> + <item>'Inactive' - if target transaction has already been prepared.</item> + </list> + </desc> + </func> + <func> + <name>get_transaction_name(Coordinator) -> Name</name> + <fsummary>Return the name associated with the object.</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Name = string() of type "oe_name@machine_type_timestamp"</v> + </type> + <desc> + <p>Returns a printable string, which describe the transaction. The main purpose is to support debugging.</p> + </desc> + </func> + <func> + <name>get_parent_status(Coordinator) -> Status</name> + <fsummary>Return the status of the parent transaction.</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Status = atom()</v> + </type> + <desc> + <p>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 <c>get_status/1</c> operation. </p> + <p>Possible Status replies:</p> + <list type="bulleted"> + <item>'StatusCommitted'</item> + <item>'StatusCommitting'</item> + <item>'StatusMarkedRollback'</item> + <item>'StatusRollingBack'</item> + <item>'StatusRolledBack'</item> + <item>'StatusActive'</item> + <item>'StatusPrepared'</item> + <item>'StatusUnknown'</item> + <item>'StatusNoTransaction'</item> + <item>'StatusPreparing'</item> + </list> + </desc> + </func> + <func> + <name>get_status(Coordinator) -> Status</name> + <fsummary>Return the status of the transaction associated with the target object</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Status = atom()</v> + </type> + <desc> + <p>Returns the status of the transaction associated with the target object.</p> + </desc> + </func> + <func> + <name>get_top_level_status(Coordinator) -> Status</name> + <fsummary>Return the status of the top-level transaction associated with the target object</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Status = atom()</v> + </type> + <desc> + <p>Returns the status of the top-level transaction associated with the target object.</p> + </desc> + </func> + <func> + <name>hash_top_level_tran(Coordinator) -> Return</name> + <fsummary>Return a hash code for the top-level transaction associated with the target object</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Return = integer()</v> + </type> + <desc> + <p>Returns a hash code for the top-level transaction + associated with the target object. Equals the operation + <c>hash_transaction/1</c> if the target object is a top-level transaction.</p> + </desc> + </func> + <func> + <name>hash_transaction(Coordinator) -> Return</name> + <fsummary>Return a hash code for the transaction associated with the target object.</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Return = integer()</v> + </type> + <desc> + <p>Returns a hash code for the transaction associated with the target object.</p> + </desc> + </func> + <func> + <name>is_descendant_transaction(Coordinator, OtherCoordinator) -> Return</name> + <fsummary>Return a boolean which indicates whether the transaction associated with the target object is a descendant of the transaction associated with the parameter object</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>OtherCoordinator = #objref</v> + <v>Return = Boolean</v> + </type> + <desc> + <p>Returns true if the transaction associated with the target object is a + descendant of the transaction associated with the parameter object.</p> + </desc> + </func> + <func> + <name>is_same_transaction(Coordinator, OtherCoordinator) -> Return</name> + <fsummary>Return true if the transaction associated with the target object is related to the transaction associated with the parameter object</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>OtherCoordinator = #objref</v> + <v>Return = Boolean</v> + </type> + <desc> + <p>Returns true if the transaction associated with the target object is + related to the transaction associated with the parameter object.</p> + </desc> + </func> + <func> + <name>is_top_level_transaction(Coordinator) -> Return</name> + <fsummary>Return true if the transaction associated with the target object is a top-level transaction</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Return = Boolean</v> + </type> + <desc> + <p>Returns true if the transaction associated with the target object is + a top-level transaction.</p> + </desc> + </func> + <func> + <name>register_resource(Coordinator, Resource) -> RecoveryCoordinator</name> + <fsummary>Register the parameter <c>Resource</c>object as a participant in the transaction associated with the target object</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Resource = #objref</v> + <v>RecoveryCoordinator = #objref</v> + </type> + <desc> + <p>This operation registers the parameter <c>Resource</c> object as a participant in the + transaction associated with the target object. The <c>RecoveryCoordinator</c> returned + by this operation can be used by this Resource during recovery.</p> + <note> + <p>The Resources will be called in FIFO-order when preparing or committing. + Hence, be sure to register the Resources in the correct order.</p> + </note> + <p>Raises exception:</p> + <list type="bulleted"> + <item>'Inactive' - if target transaction has already been prepared.</item> + </list> + </desc> + </func> + <func> + <name>register_subtran_aware(Coordinator, SubtransactionAwareResource) -> Return</name> + <fsummary>Register the parameter <c>SubtransactionAwareResource</c>object such that it will be notified when the transaction, associated wit the target object, has committed or rolled back</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Return = ok</v> + </type> + <desc> + <p>This operation registers the parameter <c>SubtransactionAwareResource</c> object such that + it will be notified when the transaction, associated wit the target object, + has committed or rolled back.</p> + <note> + <p>The Resources will be called in FIFO-order. + Hence, be sure to register the Resources in the correct order.</p> + </note> + </desc> + </func> + <func> + <name>rollback_only(Coordinator) -> Return</name> + <fsummary>Modify the transaction associated with the target object so the only possible outcome is to rollback the transaction</fsummary> + <type> + <v>Coordinator = #objref</v> + <v>Return = ok</v> + </type> + <desc> + <p>The transaction associated with the target object is modified so the only + possible outcome is to rollback the transaction.</p> + </desc> + </func> + </funcs> + +</erlref> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>CosTransactions_­RecoveryCoordinator</title> + <shorttitle>..._RecoveryCoordinator</shorttitle> + <prepared>Niclas Eklund</prepared> + <responsible>Niclas Eklund</responsible> + <docno></docno> + <approved>Niclas Eklund</approved> + <checked></checked> + <date>1999-04-12</date> + <rev>PA1</rev> + </header> + <module>CosTransactions_RecoveryCoordinator</module> + <modulesummary>This module implements the OMG CosTransactions::RecoveryCoordinator interface.</modulesummary> + <description> + <p>To get access to the record definitions for the structures use: <br></br> +<c>-include_lib("cosTransactions/include/CosTransactions.hrl").</c></p> + </description> + <funcs> + <func> + <name>replay_completion(RecoveryCoordinator, Timeout, Resource) -> Return</name> + <fsummary>Return the current status of the transaction</fsummary> + <type> + <v>RecoveryCoordinator = #objref</v> + <v>Timeout = integer(), milliseconds | 'infinity'</v> + <v>Resource = #objref</v> + <v>Return = Status | {'EXCEPTION', E}</v> + <v>E = #'CosTransactions_NotPrepared'{}</v> + <v>Status = atom()</v> + </type> + <desc> + <p>The <c>RecoveryCoordinator</c> object is returned by the operation + <c>CosTransactions_Coordinator:register_resource/3</c>. The <c>replay_completion/2</c> + 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.</p> + <p>Possible Status replies:</p> + <list type="bulleted"> + <item>'StatusCommitted'</item> + <item>'StatusCommitting'</item> + <item>'StatusMarkedRollback'</item> + <item>'StatusRollingBack'</item> + <item>'StatusRolledBack'</item> + <item>'StatusActive'</item> + <item>'StatusPrepared'</item> + <item>'StatusUnknown'</item> + <item>'StatusNoTransaction'</item> + <item>'StatusPreparing'</item> + </list> + <warning> + <p><em>replay_completion/3</em> 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'.</p> + <p>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.</p> + </warning> + </desc> + </func> + </funcs> + +</erlref> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>CosTransactions_Resource</title> + <prepared></prepared> + <docno></docno> + <checked></checked> + <date>1999-04-12</date> + <rev>PA1</rev> + </header> + <module>CosTransactions_Resource</module> + <modulesummary>This module implements the OMG CosTransactions::Resource interface.</modulesummary> + <description> + <p>To get access to the record definitions for the structures use: <br></br> +<c>-include_lib("cosTransactions/include/CosTransactions.hrl").</c></p> + </description> + <funcs> + <func> + <name>commit(Resource) -> Return</name> + <fsummary>Instruct the target object to commit the transaction</fsummary> + <type> + <v>Resource = #objref</v> + <v>Return = ok | {'EXCEPTION', E}</v> + <v>E = #'CosTransactions_NotPrepared'{} | #'CosTransactions_HeuristicRollback'{} | #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazard'{}</v> + </type> + <desc> + <p>This operation instructs the Resource to commit all changes made as a part of the transaction.</p> + <p>The Resource can raise:</p> + <list type="bulleted"> + <item>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 <c>forget</c> operation is performed.</item> + </list> + </desc> + </func> + <func> + <name>commit_one_phase(Resource) -> Return</name> + <fsummary>Instruct the target object to commit the transaction</fsummary> + <type> + <v>Resource = #objref</v> + <v>Return = ok | {'EXCEPTION', E}</v> + <v>E = #'CosTransactions_HeuristicHazard'{} | #'CosTransactions_TransactionRolledBack'{}</v> + </type> + <desc> + <p>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.</p> + </desc> + </func> + <func> + <name>forget(Resource) -> Return</name> + <fsummary>Instruct the target object to forget any heuristic decisions</fsummary> + <type> + <v>Resource = #objref</v> + <v>Return = ok</v> + </type> + <desc> + <p>This operation informs the Resource that it is safe to forget any Heuristic + decisions and the knowledge of the transaction.</p> + </desc> + </func> + <func> + <name>prepare(Resource) -> Return</name> + <fsummary>Instruct the target object to begin the two-phase commit protocol</fsummary> + <type> + <v>Resource = #objref</v> + <v>Return = Vote | {'EXCEPTION', E}</v> + <v>Vote = 'VoteReadOnly' | 'VoteCommit' | 'VoteRollback'</v> + <v>E = #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazard'{}</v> + </type> + <desc> + <p>This operation is invoked on the Resource to begin the two-phase commit protocol.</p> + <p>The Resource can reply:</p> + <list type="bulleted"> + <item>'VoteReadOnly' - if no persistent data has been modified by the transaction. + The Resource can forget all knowledge of the transaction. </item> + <item>'VoteCommit' - if the Resource has been prepared and is able to write all the + data needed to commit the transaction to stable storage.</item> + <item>'VoteRollback' - under any circumstances but must do so if none of the alternatives above + are applicable.</item> + <item>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 <c>forget</c> operation is performed.</item> + </list> + </desc> + </func> + <func> + <name>rollback(Resource) -> Return</name> + <fsummary>Instruct the target object to rollback the transaction</fsummary> + <type> + <v>Resource = #objref</v> + <v>Return = ok | {'EXCEPTION', E}</v> + <v>E = #'CosTransactions_HeuristicCommit'{} | #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazard'{}</v> + </type> + <desc> + <p>This operation instructs the Resource to rollback all changes made as a part of the transaction.</p> + <p>The Resource can raise:</p> + <list type="bulleted"> + <item>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 <c>forget</c> operation is performed.</item> + </list> + </desc> + </func> + </funcs> + +</erlref> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>CosTransactions_­SubtransactionAwareResource</title> + <shorttitle>..._SubtransactionAwareResource</shorttitle> + <prepared></prepared> + <docno></docno> + <checked></checked> + <date>1999-04-12</date> + <rev>PA1</rev> + </header> + <module>CosTransactions_SubtransactionAwareResource</module> + <modulesummary>This module implements the OMG CosTransactions::SubtransactionAwareResource interface.</modulesummary> + <description> + <p>This interface inherits the CosTransactions::Resource interface. Hence, + it must also support all operations defined in the Resource interface.</p> + <p>To get access to the record definitions for the structures use: <br></br> +<c>-include_lib("cosTransactions/include/CosTransactions.hrl").</c></p> + </description> + <funcs> + <func> + <name>commit_subtransaction(SubtransactionAwareResource, Coordinator) -> Return</name> + <fsummary>Notify the target object that the transaction has committed</fsummary> + <type> + <v>SubtransactionAwareResource = #objref</v> + <v>Coordinator = #objref</v> + <v>Return = ok</v> + </type> + <desc> + <p>If the <c>SubtransactionAwareResource</c> have been registered with a <em>subtransaction</em> + using the operation <c>CosTransactions_Coordinator:register_subtran_aware/2</c>, + it will be notified when the transaction has committed.</p> + <note> + <p>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.</p> + </note> + </desc> + </func> + <func> + <name>rollback_subtransaction(SubtransactionAwareResource) -> Return</name> + <fsummary>Notify the target object that the transaction has been rolled back</fsummary> + <type> + <v>SubtransactionAwareResource = #objref</v> + <v>Return = ok</v> + </type> + <desc> + <p>If the <c>SubtransactionAwareResource</c> have been registered with a transactions + using the operation <c>CosTransactions_Coordinator:register_subtran_aware/2</c> + it will be notified when the transaction has rolled back.</p> + </desc> + </func> + </funcs> + +</erlref> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year> + <year>2007</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + 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. + </legalnotice> + + <title>CosTransactions_Synchronization</title> + <prepared>Niclas Eklund</prepared> + <responsible>Niclas Eklund</responsible> + <docno></docno> + <approved>Niclas Eklund</approved> + <checked></checked> + <date>1999-04-12</date> + <rev>PA1</rev> + </header> + <module>CosTransactions_Synchronization</module> + <modulesummary>This module implements the OMG CosTransactions::Synchronization interface.</modulesummary> + <description> + <p>To get access to the record definitions for the structures use: <br></br> +<c>-include_lib("cosTransactions/CosTransactions.hrl").</c></p> + </description> + <funcs> + <func> + <name>before_completion(Synchronization) -> Return</name> + <fsummary>Notify the target object that the transaction is about to enter the prepare phase</fsummary> + <type> + <v>Synchronization = #objref</v> + <v>Return = ok</v> + </type> + <desc> + <p>If the target object is a transaction using the operation <c>register_synchronization/2</c> + it will be notified to perform necessary processing prior to the prepare phase.</p> + </desc> + </func> + <func> + <name>after_completion(Synchronization) -> Return</name> + <fsummary>Notify the target object that the transaction is completed</fsummary> + <type> + <v>Synchronization = #objref</v> + <v>Return = ok</v> + </type> + <desc> + <p>If the target object is a transaction using the operation <c>register_synchronization/2</c> + it will be notified to perform necessary processing after terminating the transaction.</p> + </desc> + </func> + </funcs> + +</erlref> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year> + <year>2007</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + 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. + </legalnotice> + + <title>CosTransactions_Terminator</title> + <prepared>Niclas Eklund</prepared> + <responsible>Niclas Eklund</responsible> + <docno></docno> + <approved>Niclas Eklund</approved> + <checked></checked> + <date>1999-04-12</date> + <rev>PA1</rev> + </header> + <module>CosTransactions_Terminator</module> + <modulesummary>This module implements the OMG CosTransactions::Terminator interface.</modulesummary> + <description> + <p>To get access to the record definitions for the structures use: <br></br> +<c>-include_lib("cosTransactions/include/CosTransactions.hrl").</c></p> + </description> + <funcs> + <func> + <name>commit(Terminator, ReportHeuristics) -> Return</name> + <fsummary>Try to commit a transaction</fsummary> + <type> + <v>Terminator = #objref</v> + <v>ReportHeuristics = boolean()</v> + <v>Return = ok | {'EXCEPTION', E}</v> + <v>E = #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazrd'{} | #'CosTransactions_TransactionRolledBack'{}</v> + </type> + <desc> + <p>This operation initiates the two-phase commit protocol. If the transaction has not been marked + <c>'rollback only'</c> and all the participants agree to commit, the operation terminates normally. Otherwise, + the TransactionRolledBack is raised. If the parameter <c>ReportHeuristics</c> is true and inconsistent + outcomes by raising an Heuristic Exception.</p> + </desc> + </func> + <func> + <name>rollback(Terminator) -> Return</name> + <fsummary>Rollback a transaction</fsummary> + <type> + <v>Terminator = #objref</v> + <v>Return = ok</v> + </type> + <desc> + <p>This operation roles back the transaction. </p> + </desc> + </func> + </funcs> + +</erlref> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year> + <year>2007</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + 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. + </legalnotice> + + <title>CosTransactions_­TransactionFactory</title> + <shorttitle>..._TransactionFactory</shorttitle> + <prepared>Niclas Eklund</prepared> + <responsible>Niclas Eklund</responsible> + <docno></docno> + <approved>Niclas Eklund</approved> + <checked></checked> + <date>1999-04-12</date> + <rev>PA1</rev> + </header> + <module>CosTransactions_TransactionFactory</module> + <modulesummary>This module implements the OMG CosTransactions::TransactionFactory interface.</modulesummary> + <description> + <p>To get access to the record definitions for the structures use: <br></br> +<c>-include_lib("cosTransactions/include/CosTransactions.hrl").</c></p> + </description> + <funcs> + <func> + <name>create(TransactionFactory, Timeout) -> Control</name> + <fsummary>Create a new top-level transaction</fsummary> + <type> + <v>TransactionFactory = #objref</v> + <v>Timeout = integer()</v> + <v>Control = #objref</v> + </type> + <desc> + <p>This operation creates a new top-level transaction.</p> + <p>The <c>Timeout</c> argument can be:</p> + <list type="bulleted"> + <item>0 - no timeout.</item> + <item>N (integer() > 0) - the transaction will be subject to being rolled back + if it does not complete before N seconds have elapsed.</item> + </list> + </desc> + </func> + </funcs> + +</erlref> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>CosTransactions_TransactionalObject</title> + <prepared></prepared> + <docno></docno> + <checked></checked> + <date>1999-04-12</date> + <rev>PA1</rev> + </header> + <module>CosTransactions_TransactionalObject</module> + <modulesummary>This module implements the OMG CosTransactions::TransactionalObject interface.</modulesummary> + <description> + <p>To get access to the record definitions for the structures use: <br></br> +<c>-include_lib("cosTransactions/CosTransactions.hrl").</c></p> + <p>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.</p> + </description> + +</erlref> + 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 Binary files differnew file mode 100644 index 0000000000..94b3868792 --- /dev/null +++ b/lib/cosTransactions/doc/src/book.gif 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE book SYSTEM "book.dtd"> + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + <header titlestyle="normal"> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>cosTransactions</title> + <prepared>Niclas Eklund</prepared> + <docno></docno> + <date>1999-04-14</date> + <rev>2.0</rev> + </header> + <insidecover> + </insidecover> + <pagetext>cosTransactions</pagetext> + <preamble> + <contents level="2"></contents> + </preamble> + <parts lift="no"> + <xi:include href="part.xml"/> + </parts> + <applications> + <xi:include href="ref_man.xml"/> + </applications> + <releasenotes> + <xi:include href="notes.xml"/> + </releasenotes> + <listofterms></listofterms> + <index></index> +</book> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>The cosTransactions Application</title> + <prepared>Niclas Eklund</prepared> + <docno></docno> + <date>1999-04-14</date> + <rev>B</rev> + <file>ch_contents.xml</file> + </header> + + <section> + <title>Content Overview</title> + <p>The cosTransactions documentation is divided into three sections: + </p> + <list type="bulleted"> + <item> + <p>PART ONE - The User's Guide + <br></br> +Description of the cosTransactions Application including + services and a small tutorial demonstrating + the development of a simple service.</p> + </item> + <item> + <p>PART TWO - Release Notes + <br></br> +A concise history of cosTransactions.</p> + </item> + <item> + <p>PART THREE - The Reference Manual + <br></br> + A quick reference guide, including a + brief description, to all the functions available in cosTransactions.</p> + </item> + </list> + </section> + + <section> + <title>Brief Description of the User's Guide</title> + <p>The User's Guide contains the following parts:</p> + <list type="bulleted"> + <item> + <p>cosTransactions overview</p> + </item> + <item> + <p>cosTransactions installation</p> + </item> + <item> + <p>A tutorial example</p> + </item> + </list> + </section> +</chapter> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>cosTransactions Examples</title> + <prepared></prepared> + <docno></docno> + <date>1999-04-27</date> + <rev>A</rev> + <file>ch_example.xml</file> + </header> + + <section> + <title>A Tutorial on How to Create a Simple Service</title> + + <section> + <title>Interface design</title> + <p>To use the cosTransactions application <em>participants</em> must be implemented. + There are two types of participants: </p> + <list type="bulleted"> + <item><seealso marker="CosTransactions_Resource">CosTransactions_Resource</seealso> - operations used to commit or rollback resources.</item> + <item><seealso marker="CosTransactions_SubtransactionAwareResource">CosTransactions_SubtransactionAwareResource</seealso> - + operations used when the resources want to be notified when a subtransaction commits. + This interface inherits the CosTransactions_Resource</item> + </list> + <p>The interfaces for these participants are defined in <em>CosTransactions.idl</em></p> + </section> + + <section> + <title>Generating a Participant Interface</title> + <p>We start by creating an interface which inherits from <em>CosTransactions::Resource</em>. Hence, + we must also implement all operations defined in the Resource interface. The IDL-file could look like: </p> + <code type="c"><![CDATA[ +#ifndef _OWNRESOURCEIMPL_IDL +#define _OWNRESOURCEIMPL_IDL +#include <CosTransactions.idl> + +module ownResourceImpl { + + interface ownInterface:CosTransactions::Resource { + + void ownFunctions(in any NeededArguments) + raises(Systemexceptions,OwnExceptions); + + }; +}; + +#endif + ]]></code> + <p>Run the IDL compiler on this file by calling the <c>ic:gen/1</c> function. + This will produce the API named <c>ownResourceImpl_ownInterface.erl</c>. + 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 <c>ownResourceImpl_ownInterface_impl.erl</c>.</p> + </section> + + <section> + <title>Implementation of Participant interface</title> + <p>If the participant is intended to be a plain Resource, we must implement the following operations:</p> + <list type="bulleted"> + <item><c>prepare/1</c> - this operation is invoked on the Resource to begin the two-phase commit protocol.</item> + <item><c>rollback/1</c> - this operation instructs the Resource to rollback all changes made as a part of the transaction. </item> + <item><c>commit/1</c> - this operation instructs the Resource to commit all changes made as a part of the transaction.</item> + <item><c>commit_one_phase/1</c> - 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. </item> + <item><c>forget/1</c> - this operation informs the Resource that it is safe to forget any + <term id="Heuristic decisions"><termdef>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.</termdef></term>and the knowledge of the transaction.</item> + <item><c>ownFunctions</c> - all application specific operations.</item> + </list> + <p>If the participant wants to be notified when a subtransaction commits, we must also implement the following operations + (besides the operations above):</p> + <list type="bulleted"> + <item><c>commit_subtransaction/2</c> - if the <c>SubtransactionAwareResource</c> have been registered + with a transactions using the operation <c>CosTransactions_Coordinator:register_subtran_aware/2</c> it will + be notified when the transaction has + committed. </item> + <item><c>rollback_subtransaction/1</c> - if the <c>SubtransactionAwareResource</c> have been registered + with a transactions using the operation <c>CosTransactions_Coordinator:register_subtran_aware/2</c> + it will be notified when the transaction has + rolled back. </item> + </list> + <note> + <p>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. </p> + </note> + </section> + + <section> + <title>Participant Operations Behavior</title> + <p>Each application participant must behave in a certain way to ensure that the two-phase commit protocol + can complete the transactions correctly.</p> + + <section> + <title>prepare</title> + <p>This operation ask the participant to vote on the outcome of the transaction. Possible replies are:</p> + <list type="bulleted"> + <item><em>'VoteReadOnly'</em> - 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.</item> + <item><em>'VoteCommit'</em> - 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 <seealso marker="CosTransactions_Resource">Heuristic Exception</seealso> and wait + until the <c>forget</c> operation is invoked. The Heuristic Decision must be recorded in stable storage.</item> + <item><em>'VoteRollback'</em> - the Resource may vote VoteRollback under any circumstances. + The Resource can forget all knowledge of the transaction and terminate.</item> + </list> + <note> + <p>Before replying to the prepare operation, the Resource must record the prepare state, the reference of its + superior <seealso marker="CosTransactions_RecoveryCoordinator">RecoveryCoordinator</seealso> in stable storage. + The RecoveryCoordinator is obtained when registering as a participant in a transaction.</p> + </note> + </section> + + <section> + <title>rollback</title> + <p>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.</p> + </section> + + <section> + <title>commit</title> + <p>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.</p> + </section> + + <section> + <title>commit_one_phase</title> + <p>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.</p> + </section> + + <section> + <title>forget</title> + <p>If the Resource raised a Heuristic Exception to <c>commit</c>, <c>rollback</c> or <c>commit_one_phase</c> this operation + will be performed. The Resource can forget all knowledge of the transaction and terminate.</p> + </section> + + <section> + <title>commit_subtransaction</title> + <p>If the <c>SubtransactionAwareResource</c> have been registered with a <em>subtransaction</em> + using the operation <c>CosTransactions_Coordinator:register_subtran_aware/2</c> + it will be notified when the transaction has committed. The Resource may raise the exception + <c>'TRANSACTION_ROLLEDBACK'</c>.</p> + <note> + <p>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.</p> + </note> + </section> + + <section> + <title>rollback_subtransaction</title> + <p>If the <c>SubtransactionAwareResource</c> have been registered with a <em>subtransaction</em> + using the operation <c>CosTransactions_Coordinator:register_subtran_aware/2</c> + it will be notified when the subtransaction has rolled back.</p> + </section> + </section> + + <section> + <title>How to Run Everything</title> + <p>Below is a short transcript on how to run cosTransactions. </p> + <code type="none"> + +%% 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)), + </code> + <note> + <p>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.</p> + </note> + <p>The outcome of the transaction can be:</p> + <list type="bulleted"> + <item>ok - the transaction was successfully committed.</item> + <item>{'EXCEPTION', HeuristicExc} - at least one participant made a + Heuristic decision or, due to a failure, one or more participants + where unreachable.</item> + <item>{'EXCEPTION', #'TRANSACTION_ROLLEDBACK'{}} - + the transaction was successfully rolled back.</item> + <item>Any system exception - + the transaction failed with unknown reason.</item> + </list> + </section> + </section> +</chapter> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>Installing cosTransactions</title> + <prepared></prepared> + <docno></docno> + <date>1999-04-20</date> + <rev></rev> + <file>ch_install.xml</file> +</header> + + <section> + <title>Installation Process </title> + <p>This chapter describes how to install + <seealso marker="cosTransactions">cosTransactions</seealso> + in an Erlang Environment. + </p> + + <section> + <title>Preparation</title> + <p>Before starting the installation process for cosTransactions, + the application Orber must be running.</p> + <p>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, <c>read</c> and + <c>write</c> 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.</p> + </section> + + <section> + <title>Configuration</title> + <p>When using the Transaction Service the <c>cosTransactions</c> application + must be started using either <c>cosTransactions:start()</c> or + <c>application:start(cosTransactions)</c>. + </p> + <p>The following application configuration parameters exist:</p> + <list type="bulleted"> + <item><c>maxRetries</c> - default is 40 times, i.e., if a transaction participant is unreachable + the application will retry to contact it <c>N</c> times. Reaching the maximum is considered to be a disaster.</item> + <item><c>comFailWait</c> - default is 5000 milliseconds, i.e., before the application + retries to contact unreachable transaction participants the application wait <c>Time</c> milliseconds.</item> + </list> + <p>Then the <seealso marker="CosTransactions_TransactionFactory">Transaction Factory</seealso> + must be started:</p> + <list type="bulleted"> + <item><c>cosTransactions:start_factory()</c> - starts and returns a reference to a factory using default configuration parameters.</item> + <item><c>cosTransactions:start_factory(Options)</c> - starts and returns a reference to a factory using given configuration parameters.</item> + </list> + <p>The following options exist: + </p> + <list type="bulleted"> + <item><c>{hash_max, HashValue}</c> - + This value denotes the upper bound of the hash value the <seealso marker="CosTransactions_Coordinator">Coordinator</seealso> uses. + Default is <c>1013</c>. HashValue must be an integer.</item> + <item><c>{allow_subtr, Boolean}</c> - + If set to true it is possible to create <seealso marker="CosTransactions_Coordinator">subtransactions</seealso>. + Default is <c>true</c>.</item> + <item><c>{typecheck, Boolean}</c> - + If set to to true all transaction operation's arguments will be type-checked. + Default is <c>true</c>.</item> + <item><c>{tty, Boolean}</c> - + 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. </item> + <item><c>{logfile, FileName}</c> - + This function makes it possible to store all system information in <c>FileName</c> (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.</item> + <item><c>{maxRetries, Integer}</c> - + default is 40 times, i.e., if a transaction participant is unreachable the application will + retry to contact it <c>N</c> times. Reaching the maximum is considered to be a disaster. + This option overrides the application configuration parameter.</item> + <item><c>{comFailWait, Integer}</c> - + default is 5000 milliseconds, i.e., before the application retries to contact unreachable + transaction participants the application wait <c>Time</c> milliseconds. + This option overrides the application configuration parameter.</item> + </list> + <p>The Factory is now ready to use. For a more detailed description see <seealso marker="ch_example">Examples</seealso>. + </p> + </section> + </section> +</chapter> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>Introduction to cosTransactions</title> + <prepared>Niclas Eklund</prepared> + <docno></docno> + <date>1999-04-26</date> + <rev></rev> + <file>ch_introduction.xml</file> +</header> + + <section> + <title>Overview</title> + <p>The cosTransactions application is a Transaction Service compliant with the <url href="http://www.omg.org">OMG</url> + Transaction Service CosTransactions 1.1. + </p> + + <section> + <title>Purpose and Dependencies</title> + <p><em>cosTransactions</em> is dependent on <em>Orber version 3.0.1</em> or later(see the Orber + documentation), which provides CORBA functionality in an Erlang environment.</p> + <p><em>cosTransactions</em> is dependent on <em>supervisor/stdlib-1.7</em> or later.</p> + <p>Basically, cosTransaction implements a <em>two-phase commit protocol</em> and allows objects running + on different platforms to participate in a transaction.</p> + </section> + + <section> + <title>Prerequisites</title> + <p>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. + </p> + <p>Recommended reading includes <em>CORBA, Fundamentals and Programming - Jon Siegel</em> and <em>Open Telecom Platform Documentation Set</em>. It is also helpful to have read + <em>Concurrent Programming in Erlang</em> and, for example, <em>Transaction Processing: concepts and techniques - Jim Gray, Andreas Reuter</em>.</p> + <note> + <p>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 <c>'TRANSACTION_REQUIRED', 'TRANSACTION_ROLLEDBACK'</c> and <c>'INVALID_TRANSACTION'</c> + exceptions have been redefined to be system exceptions, i.e., used to be transaction-specific ('CosTransactions_Exc').</p> + </note> + </section> + </section> +</chapter> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>Resource Skeletons</title> + <prepared>Niclas Eklund</prepared> + <docno></docno> + <date>1999-04-29</date> + <rev></rev> + <file>ch_skeletons.xml</file> + </header> + + <section> + <title>Resource Skeletons</title> + <p>This chapter provides a skeleton for application Resources. For more information + see the Orber documentation.</p> + <code type="none"> +%%%----------------------------------------------------------- +%%% 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 ------------------------------ + </code> + </section> +</chapter> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year> + <year>2007</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + 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. + </legalnotice> + + <title>cosTransactions</title> + <prepared>Niclas Eklund</prepared> + <responsible>Niclas Eklund</responsible> + <docno></docno> + <approved>Niclas Eklund</approved> + <checked></checked> + <date>1999-04-23</date> + <rev>PA1</rev> + </header> + <module>cosTransactions</module> + <modulesummary>The main module of the cosTransactions application.</modulesummary> + <description> + <p>To get access to the record definitions for the structures use: <br></br> +<c>-include_lib("cosTransactions/include/CosTransactions.hrl").</c></p> + <p>This module contains the functions for starting and stopping the application. + If the application is started using <c>application:start(cosTransactions)</c> the + default configuration is used (see listing below). The Factory reference is stored using the CosNaming Service + under the id <c>"oe_cosTransactionsFac_IPNo"</c>.</p> + <p>The following application configuration parameters exist:</p> + <list type="bulleted"> + <item><em>maxRetries</em> - default is 40 times, i.e., if a transaction participant is unreachable + the application will retry to contact it <c>N</c> times. Reaching the maximum is considered to be a disaster.</item> + <item><em>comFailWait</em> - default is 5000 milliseconds, i.e., before the application + retries to contact unreachable transaction participants the application wait <c>Time</c> milliseconds.</item> + </list> + </description> + <funcs> + <func> + <name>start() -> Return</name> + <fsummary>Start the cosTransactions application</fsummary> + <type> + <v>Return = ok | {error, Reason}</v> + </type> + <desc> + <p>This operation starts the cosTransactions application.</p> + </desc> + </func> + <func> + <name>stop() -> Return</name> + <fsummary>Stop the cosTransactions application</fsummary> + <type> + <v>Return = ok | {error, Reason}</v> + </type> + <desc> + <p>This operation stops the cosTransactions application.</p> + </desc> + </func> + <func> + <name>start_factory() -> TransactionFactory</name> + <fsummary>Start a <c>Transaction Factory</c></fsummary> + <type> + <v>TransactionFactory = #objref</v> + </type> + <desc> + <p>This operation creates a <seealso marker="CosTransactions_TransactionFactory">Transaction Factory</seealso>. + The Factory is used to create a new top-level <seealso marker="CosTransactions_Control">transaction</seealso> using default options (see listing below).</p> + </desc> + </func> + <func> + <name>start_factory(FacDef) -> TransactionFactory</name> + <fsummary>Start a <c>Transaction Factory</c>with given options</fsummary> + <type> + <v>FacDef = [Options], see Option listing below.</v> + <v>TransactionFactory = #objref</v> + </type> + <desc> + <p>This operation creates a <seealso marker="CosTransactions_TransactionFactory">Transaction Factory</seealso>. + The Factory is used to create a new top-level transaction. </p> + <p>The FacDef list must be a list of {Item, Value} tuples, + where the following values are allowed: </p> + <list type="bulleted"> + <item>{hash_max, HashValue} - + This value denotes the upper bound of the hash value the + <seealso marker="CosTransactions_Coordinator">Coordinator</seealso> uses. + Default is <c>1013</c>. HashValue must be an integer.</item> + <item>{allow_subtr, Boolean} - + If set to true it is possible to create <seealso marker="CosTransactions_Coordinator">subtransactions</seealso>. + Default is <c>true</c>.</item> + <item>{typecheck, Boolean} - + If set to to true all transaction operation's arguments will be type-checked. + Default is <c>true</c>.</item> + <item>{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. </item> + <item>{logfile, FileName} - + This function makes it possible to store all system information in <c>FileName</c> (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.</item> + <item><c>{maxRetries, Integer}</c> - + default is 40 times, i.e., if a transaction participant is unreachable the application will + retry to contact it <c>N</c> times. Reaching the maximum is considered to be a disaster. + This option overrides the application configuration parameter.</item> + <item><c>{comFailWait, Integer}</c> - + default is 5000 milliseconds, i.e., before the application retries to contact unreachable + transaction participants the application wait <c>Time</c> milliseconds. + This option overrides the application configuration parameter.</item> + </list> + </desc> + </func> + <func> + <name>stop_factory(TransactionFactory) -> Reply</name> + <fsummary>Terminate the target object</fsummary> + <type> + <v>TransactionFactory = #objref</v> + <v>Reply = ok | {'EXCEPTION', E}</v> + </type> + <desc> + <p>This operation stop the target transaction factory.</p> + </desc> + </func> + </funcs> + +</erlref> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> + +<fascicules> + <fascicule file="part" href="part_frame.html" entry="no"> + User's Guide + </fascicule> + <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> + Reference Manual + </fascicule> + <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> + Release Notes + </fascicule> + <fascicule file="" href="../../../../doc/print.html" entry="no"> + Off-Print + </fascicule> +</fascicules> + 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 Binary files differnew file mode 100644 index 0000000000..e000cca26a --- /dev/null +++ b/lib/cosTransactions/doc/src/notes.gif 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>cosTransactions Release Notes</title> + <prepared>Niclas Eklund</prepared> + <responsible>Niclas Eklund</responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>99-04-14</date> + <rev>A</rev> + <file>notes.xml</file> + </header> + + <section> + <title>cosTransactions 1.2.8</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p> + 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.</p> + <p> + Own Id: OTP-8201 Aux Id:</p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.2.7</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Obsolete guards, e.g. record vs is_record, has been changed + to avoid compiler warnings.</p> + <p>Own id: OTP-7987</p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.2.6</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Updated file headers.</p> + <p>Own id: OTP-7837</p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.2.5</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Documentation source included in open source releases.</p> + <p>Own id: OTP-7595</p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.2.4</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Updated file headers.</p> + <p>Own id: OTP-7011</p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.2.3</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The documentation source has been converted from SGML to XML.</p> + <p>Own id: OTP-6754 Aux Id: </p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.2.2</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Minor Makefile changes.</p> + <p>Own id: OTP-6701 Aux Id: </p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.2.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Removed some unused code.</p> + <p>Own id: OTP-6527 Aux Id: </p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.2</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>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.</p> + <p>Own id: OTP-4576</p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.1.2</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>To avoid un-necessary Heuristic decisions cosTransactions now + recognize more systems exceptions.</p> + <p>Own Id: OTP-4485</p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.1.1.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Updated internal documentation.</p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.1.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>cosTransactions is now able to handle upgrade properly.</p> + <p>Own Id: -</p> + </item> + <item> + <p>The cosTransactions factory now accepts <c>maxRetries</c> and + <c>comFailWait</c> options, which overrides the configuration parameters.</p> + <p>Own Id: -</p> + </item> + </list> + </section> + + <section> + <title>Incompatibilities</title> + <list type="bulleted"> + <item> + <p>The configuration parameters <c>comm_failure_wait</c> and <c>max_retries</c> + changed to <c>maxRetries</c> and <c>comFailWait</c>. The default value for + <c>maxRetries</c> have been raised from 20 to 40.</p> + <p>Own Id: -</p> + </item> + </list> + </section> + </section> + + <section> + <title>cosTransactions 1.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>First release of the cosTransactions application.</p> + <p>Own Id: OTP-1741</p> + </item> + </list> + </section> + </section> +</chapter> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>cosTransactions User's Guide</title> + <prepared>Niclas Eklund</prepared> + <docno></docno> + <date>1999-04-20</date> + <rev>2.2</rev> + </header> + <description> + <p>The <em>cosTransactions</em> application is an Erlang implementation + of the OMG CORBA Transaction Service.</p> + </description> + <xi:include href="ch_contents.xml"/> + <xi:include href="ch_introduction.xml"/> + <xi:include href="ch_install.xml"/> + <xi:include href="ch_example.xml"/> + <xi:include href="ch_skeletons.xml"/> +</part> + 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>cosTransactions Release Notes</title> + <prepared></prepared> + <docno></docno> + <date>1999-04-14</date> + <rev>2.0</rev> + </header> + <description> + <p>The cosTransactions Application is an Erlang implementation of the OMG + CORBA Transaction Service.</p> + </description> + <xi:include href="notes.xml"/> +</part> + diff --git a/lib/cosTransactions/doc/src/ref_man.gif b/lib/cosTransactions/doc/src/ref_man.gif Binary files differnew file mode 100644 index 0000000000..b13c4efd53 --- /dev/null +++ b/lib/cosTransactions/doc/src/ref_man.gif 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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> + +<application xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>1999</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>cosTransactions Reference Manual</title> + <prepared>Niclas Eklund</prepared> + <docno></docno> + <date>1999-04-14</date> + <rev>2.0</rev> + </header> + <description> + <p>The <em>cosTransactions</em> application is an Erlang implementation + of the OMG CORBA Transaction Service.</p> + </description> + <xi:include href="cosTransactions.xml"/> + <xi:include href="CosTransactions_Control.xml"/> + <xi:include href="CosTransactions_Coordinator.xml"/> + <xi:include href="CosTransactions_RecoveryCoordinator.xml"/> + <xi:include href="CosTransactions_Resource.xml"/> + <xi:include href="CosTransactions_SubtransactionAwareResource.xml"/> + <xi:include href="CosTransactions_Terminator.xml"/> + <xi:include href="CosTransactions_TransactionFactory.xml"/> +</application> + 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 Binary files differnew file mode 100644 index 0000000000..e6275a803d --- /dev/null +++ b/lib/cosTransactions/doc/src/user_guide.gif |
