[jbossts-issues] [JBoss JIRA] Created: (JBTM-780) Integrate feedback from Andrew Dinn
Misty Stanley-Jones (JIRA)
jira-events at lists.jboss.org
Sun Aug 22 23:23:12 EDT 2010
Integrate feedback from Andrew Dinn
-----------------------------------
Key: JBTM-780
URL: https://jira.jboss.org/browse/JBTM-780
Project: JBoss Transaction Manager
Issue Type: Sub-task
Security Level: Public (Everyone can see)
Reporter: Misty Stanley-Jones
Title Page
'Web Services Transactions' ought to capitalize it's 'T' here since
this use identifies a category of transaction rather than a
collection of them.
Also can we lose the prefix and just call this the XTS Programmer's
Guide? XTS stands for XML Transactions Service (which is a pretty dumb
name but that's legacy for you) so the full shebang expands (to those
who know what it means) to something even more meaningless than the
qualified acronym. And it's rather a mouthful.
I think the real problme is that there is no such thing as a
Transactions XTS Programmer but there is such a thing as an XTS
Programmer. Epithet transfer is a horrible phenomenon.
P.1 "About This Guide"
The original text here is virtually incoherent to anyone who does not
already know what XTS is (not that it stands out much from much of
what follows in that regard). It really needs replacing entirely
"The XTS Programmer's Guide explains how to use Web Services
Transactions to ensure that distributed business processes based on
web services can be made resilient to system or network failures. XTS
(XML Transaction Service) is JBoss's implementation of Web Services
Transactions. It supports development and deployment of
transaction-aware web services. It also enables web service clients to
create and manage web service transactions from which they can then
invoke transactional web services. XTS ensures that the client and web
services achieve consistent outcomes even if the systems on which they
are running crash or temporarily lose network connectivity.
"XTS is compliant with the WS-Coordination, WS-Atomic Transaction and
WS-Business Activity specifications. The implementation supports web
services and clients which are based on the JaxWS standard; indeed,
XTS is itself implemented using services based on JaxWS. While this
guide discusses many Web Services standards like SOAP and WSDL, it
does not attempt to address all of their fundamental
constructs. However, basic concepts are provided where necessary."
P.1 Prerequisites
"Web services" This really ought always to be capitalised on both
words as Web Services when it refers to the category or lower case on
both words when it refers to one or more specific web services.
"XML, SOAP, WSDL and UDDI" Drop UDDI as it is not mentioned and not
needed
"WS-C, WS-Atomic Transaction" Here and elsewhere WS-C should be
spelled out as WS-Coordination whenever WS-AT or WS-BA is also spelled
out.
P. 3 Introduction para 2
"The JBoss Transaction Service Web Services API supports ..."
Afraid that actually has to read "The JBoss Transaction Service Web
Services Transactions API supports ..." It is misleading to suggest
that JBossTS provides a Web Services API -- that's done by
JBossWS. Perhaps "XTS API" might be better here?
P.3 Protocols included in XTS
XTS also automatically implements version 1.2 of these specs since
they are functionally equivalent to 1.1. Perhaps this coudl also go in
the note.
P 3. para after note
"These standards-based communication technologies customers,
suppliers, and ..."
should be
"These standards-based communication technologies allow customers,
suppliers, and ..."
2.2 Servlets 2nd para
"In XTS, the active component is achieved through deployment of JaxWS
endpoints. Each XTS endpoint that can be communicated with via
SOAP/XML is published via JaxWS. Fortunately for the developer, this
occurs transparently. The only drawback is that transactional client
applications and transactional web services must reside within a
domain capable of hosting JaxWS endpoints, such as an application
server. In the case of Enterprise Application Platform, JBoss
Application Server provides this functionality."
The note should then read
"The XTS 1.0 protocol implementation is based on servlets".
2.3 SOAP Para 2
This is not worth stating.
Section 3:
I think this is too much theory too early on. However, I'm not going
to address the fact that this is not example based just now. That's a
big job which I will need to think about a lot more befor e|I can
remedy it. I'll merely try to make what is here more readable.
P.7 Diagram
"Application" probaby ought to be labelled "Client" or "Application
Client" and "Application Service" ought to be "Web Service" or
"Application Web Service" since client and web service ar eused
everywhere else in the guide to refer to these two parties to the
(distributed) application.
The label "UDDI/WSDL" shoudl really jsut be "WSDL" since UDDI is a
long dead pipe-dream.
P.8 3.1 The Coordinator 1st para
"The coordinator may be implemented as a separate service or may be
co-located with the user for improved performance ..."
Best to replace whole para with:
"Every transaction is associated with a coordinator, which is
responsible for governing the outcome of the transaction. When a
client begins a Web Service transaction it posts a create request to a
coordination service which creates the coordinator and returns its
details to the client. This service may be located in its own
container or may be colocated with the application client or with one
of the transactional web services for improved performance. The
coordination service is typically responsible for managing many
transactions in parallel so each coordinator is identified by a unique
transaction identifier.
P.8 3.1 The Coordinator 2nd and 3rd para
Change whole thing to
"The coordinator is responsible for ensuring that the web services
invoked by the client arrive at a consistent outcome. When the client
asks the coordinator to complete the transaction the coordinator
ensures that each web service is ready to confirm any provisional
changes made it has made within the scope of the transaction. It then
requests them all to make their changes. If any of the web services
indicates a problem at the confirmation stage the coordinator ensures
that all web services reject their provisional changes, reverting to
the state before the transaction started. The coordinator also reverts
all changes if the client asks it to cancel the transaction.
"The negotiation between the coordinator and the web services is
organised so as to ensure that all services will make their changes or
all of them will revert to the previous state even if the coordinator
or one of the web services crashes part way thorugh the transaction."
3.2 The Transaction Context
"... known as the Context. ... it is still helpful ...".
Scrub what lies in the middle and reword as
"The coordination service hands a context back to the application
client when it begins a transaction. This context is passed as an
extra, hidden parameter whenever the client invokes a transactional
web service. The XTS implementation saves and propagates this context
automatically with only minimal involvement required on the part of
the client. However, it is still helpful ..."
3.3 Participants
"When a service begins performing work ... to follow."
"When a web service receives its first service request in some given
transaction it enrols with the coordinator as a participant,
specifying the participant model it wishes to follow. As we have seen,
the context helpfully contains a URL for the endpoint of the
coordination service which handles enrollment requests"
P.19 4.1.1 Activation para 1
This needs changing because the 1.1 servise is not asynchronous.
The first para should be as follows
"The WS-C framework exposes an Activation Service which supports the
creation of coordinators for specific coordination protocols and
retrieval of associated contexts. Activation services are invoked
synchronously using an RPC style exchange. So, the service WSDL
defines a single port declaring a CreateCoordinationContext operation.
This operation takes an input specfying the details of the transaction
which is to be created including the type of coordination required,
timeout etc. It returns an output containing the details of the newly
created transaction context i.e. the transaction identifier,
coordination type and registration service URL."
The WSDL text in the box should be as follows
<!-- Activation Service portType Declaration -->
<wsdl:portType name="ActivationCoordinatorPortType">
<wsdl:operation name="CreateCoordinationContext">
<wsdl:input message="wscoor:CreateCoordinationContext"/>
<wsdl:output message="wscoor:CreateCoordinationContextResponse"/>
</wsdl:operation>
</wsdl:portType>
And the note at the top of p. 20 should say
"The 1.0 Activation Coordinator service employs an asynchronous message
exchange comprised of two one way messages, so an Activation Requester
service is also necessary."
p 20 4.1.2 Registration
This also needs changing as 1.1. is not asynchronous
First para replace
"The context returned by the activation service includes the URL of a
Registration Service. When a web services receieves a service request
accompanied by a transaction context it contacts the Registration
Service to enrol as a participant in the transaction. The registration
request includes a participant protocol defining the role the web
service wishes to take in the transaction. Depending upon the
coordination protocol, more than one choice of participant protocol
may be available.
"Like the activation service, the registration service assumes
synchronous communication. Thus, the service WSDL exposes a single
port declaring a Register operation. This operation takes an input
specifying the details of the participant which is to be registered
including the participant protocol type and returns a corresponding
output response."
The WSDL text in the box should be as follows
<!-- Registration Service portType Declaration -->
<wsdl:portType name="RegistrationCoordinatorPortType">
<wsdl:operation name="Register">
<wsdl:input message="wscoor:Register"/>
<wsdl:output message="wscoor:RegisterResponse"/>
</wsdl:operation>
</wsdl:portType>
The note at the bottom of p. 20 should say
"The 1.0 Registration Coordinator service employs an asynchronous
message exchange comprised of two one way messages, so a Registration
Requester service is also necessary."
P. 21 4.2 WS-Transaction
Before lauching into this we should probably re-iterate the definition
of WS-T provided on page 3
"WS-Transaction (WS-T) comprises the pair of transaction coordination
protocols, WS-Atomic Transaction (WS-AT) and WS-Business Activity
(WS-BA), which utilize the coordination framework provided by
WS-Coordination (WS-C). WS-Transactions was developed to unify
existing traditional ..."
P. 21 4.2.1 WS Coordination Foundations
The title here should really be "WS-Transaction Foundations" since
this is what is being described. Also, the subsequent text needs
reorganising.
"An important aspect of WS-Transaction that differs from traditional
transaction protocols is that a synchronous request/response model is
not assumed. This is because WS-Transaction is layered upon the
WS-Coordination protocol whose own communication patterns are
asynchronous by default, as shown in ..."
The 'because ...' reason provided here is not only no longer true it
is also not a valid rationale for the choice of asynchronous
communications. This should be changed to
"WS-Transaction is layered upon the WS-Coordination protocol, as shown
in ..."
The content in the original opening line needs to be relocated to the
end of section 4.2.1 after numbered list item 2.
"An important aspect of WS-Transaction that differs from traditional
transaction protocols is that a synchronous request/response model is
not assumed. Sequences of one way messages are used to implement
communications between the client/participant and the coordination
services appropriate to the transaction's coordination and participant
protocols. This is significant because it means that the client and
participant containers must deploy XTS service endpoints to receive
messages from the coordinator service."
"This requirement is visible in the details of the Register and
RegisterResponse messages declared in the Registration Service WSDL
above (example 4.2). The Register message contains the URL of an
endpoint in the client or web service container. This URL is used when
a WS-Transaction coordination service wishes to dispatch a message to
the clinet or web service. Similarly, the RegisterResponse message
contains a URL iendtifying an endpoint for the protocol-specific
WS-Transaction coordination service for which the client/web service
is registered, allowing messages to be addressed to the transaction
coordinator."
P. 22 Section 4.2.2 Opening para
Use of the bare word 'service' here is highly ambiguous since we have
just been talking about all sorts of services implemented by XTS. It
actually refers to an application web service. The main distinction
which the original author was trying to make is between the
transactional web service per se, i.e. acting as a web service
executing business-logic, vs the transactional web service acting as a
participant in the transaction, i.e. communicating with and responding
to its transaction coordinator (via the transaction coordination
service). It's about as clear as mud to anyone who does not already
understand it. I would rewrite the first para as follows:
"WS-Transaction distnguishes the transaction aware web service per se,
i.e. in its role executing business-logic, from the web service acting
as a participant in the transaction, i.e. communicating with and
responding to its transaction coordinator. Transaction-aware web
services deal with application clients using business-level protocols,
while the participant handles the underlying WS-Transaction protocols,
as shown Figure 4.4, “WS-Transaction Global Viewâ€."
Then in the next two paras each occurence of 'service' need to be
changed to 'web service'.
In the following paragraph (1st on p 23 after fig 4.5) the reference
to JAXTX needs to be got rid of as this is a dead specification. Also,
the explanation is rather cack-handed and attributes responsibility to
the wrogn agents. It neds rewording as follows:
"The transaction-aware web service employs a back end database
accessed via a JDBC driver which sends SQL statements to the database
for processing. However, those statements should only commit if the
enclosing web service transaction does. For this to work, the web
service must employs transaction bridging, registering a participant
with the coordinator for the web service transaction and creating a
matching XA transaction within which it can invoke the driver to make
tentative changes to the database. The web service ensures that
service requests associated with a specific web service transaction
are executed in the scope of the corresponding XA transaction,
grouping changes common to a given transaction while isolating changes
belonging to different transactions. The participant responds to
prepare, commit or rollback requests associated from the web service
transaction coordinator by forwarding the same operations to the
underlying XA transaction coordinator, thus ensuring that the local
outcome in the database corresponds with the global outcome of the web
service transaction as a whole."
P. 23 4.2.3.1 Atomic Transactions 2nd sentence
"Within the scope of an AT, services ... " to end of para.
"Within the scope of an AT, web services typically employ bridging to
allow them to access XA resources, such as databases and message
queues, under the control of the web service transaction. When the
transaction terminates, the outcome decision of the AT is propagated
to the XA resources via the participant, and the appropriate commit or
rollback actions are taken by each."
P. 32 1st para last sentence(we are in section 5.1.3)
"These handlers are designed to work with JAX-RPC and JAX-WS clients."
JAX-RPC is no longer supported in the product so it would be better to
reword this as
"These handlers are designed to work with JAX-WS client." and then add
a note which say "A JAX-RPC handler is provided for the 1.0
implementation." and then remove any further reference to the JAX-RPC
handler. In particular, the content in 5.1.3.1 is worng because it
refers to a JAX-RPC handler in the wst11 package and there is no such
handler.
P. 33 5.2.2 Service-Side Handler Configuration
The doc should only refer to JAX-RPC as a note for 1.0. So, the first
para 4th sentence should say "XTS provides a JaxWS handler ..." and
then the opening sentence of the 2nd para should say "The JaxWS
service side handler comes in two different versions."
P. 34 5.2.2.1 JAX-RPC Service Context Handlers
This should be dropped as JAX-RPC is not supported.
P. 34 5.2.2.2 JAX-WS Service Context Handlers
A spurious header "5.2.3 Implementing the Business Logic" has crept in
here. The text that follows belongs to 5.2.2.2. The spurious header is
then repeated (in the slightly modified but correct form) at the end
of the 5.2.2.2 text on p 36 as "5.2.4 Implementing the Web Service
Business Logic".
P. 35 5.2.4
This section is worse than useless as it proposes somethign which the
user cannot do, which we do not intend to do and which the bridge code
(when it eventually arrives in EAP) will make irrelevant. It should be
deleted.
P. 37 Durable2PCParticipant Signatures prepare
"The implementation can go to any lengths in order to fulfill the
implicit contract between it and the coordinator."
This was originally
"The implementation is free to do whatever it needs to in order to
fulfill the implicit contract between it and the coordinator."
I think your change misses the point of the original. Your wording
makes it sound as if the issue here is that the participant may need
to perform arbitrarily large or complex amounts of work. The original
is emphasising that that what the participant does below the call to
prepare is unconstrained by any requirements imposed by the XTS code
(other than returning one of the 3 possible return values). How much
work it does is of no significance.
P. 38 Volatile2PCParticipant Signatures prepare
Same issue as the preceding one.
P. 39 6.1.2. Business Activity
This reads badly because of the way the references get formatted.
Better phrasing would be
"All Business Activity participants are instances of one or other of
the interfaces described in Section 6.1.2.1,
“BusinessAgreementWithParticipantCompletion†or Section 6.1.2.2,
“BusinessAgreementWithCoordinatorCompletionâ€.
As a more general comment I know the original text often used terms in
the format "the XXX interface" to refer to a specific interface.
However, it is actually much more natural parlance to say "interface
XXX". So, for example at the end of para 1 of 6.1.2.1 it reads much
clearer to a programmer if it says "... as per interface
com.arjuna.wst11.BusinessAgreementWithParticipantCompletionParticipant."
(not that anything with a name that long can ever really read very
'clearly' or 'naturally')
P. 40 BusinessAgreementWithCoordinatorCompletion Signatures complete
This is rather infortunately worded. Better would be
"The coordinator is informing the participant all work it needs to do
within the scope of this business activity has been completed and taht
it should make permananent any provisional changes it has made."
P. 40 BusinessAgreementWithCoordinatorCompletion Signatures unknown
Missing 'is' "This method is deprecated ... "
P. 41 6.1.2.3. BAParticipantManager 2nd para last sentence
"This handle is an instance of the BAParticipantManager interface,
located in com.arjuna.wst11.BAParticipantManager, with the methods
listed in BAParticipantManager Methods."
The 'located in' is a mash-up. Interface BAParticipantManager is
located in package com.arjuna.wst11 so its full name (sometimes
referred to as its package-qualified name) is
com.arjuna.wst11.BAParticipantManager. So, this sentence would read
much better as
"This handle is an instance of interface
com.arjuna.wst11.BAParticipantManager with the methods listed in
BAParticipantManager Methods."
P. 41 BAParticipantManager Methods exit
"The participant uses the exit to inform the coordiantor ..."
That should be either "the exit method to inform ..." or "method exit
to inform ..."
You then edited the following sentence
"It will not be informed when (and how) the business activity
terminates."
changing it to
"It is not informed when and how the business activity terminates."
I understand your desire to normalise the narrative to present
indicative. However, this change fails to get across the point here
which is that calling exit means the participant is no longer be
involved the business activity. So, whereas normally it would
subsequently be informed when (and how) the business activity
terminates, after calling exit it will not be informed when (and how)
the business activity terminates.
The next sentence has also, perhaps, had an ambiguity opened up (or
exacerbated) by your edit from
"This method may only be invoked while the participant is in state
active (or completing in the case of a participant registered for the
ParticipantCompletion protocol)."
to
"This method may only be invoked while the participant is in the
active state, or the completing state in the case of a participant
registered for the ParticipantCompletion protocol."
The clause originally provided in paranthesis is meant to be
additional rather than alternative to the first. This would maybe be
clearer as:
"This method may only be invoked while the participant is in the
active state, or also the completing state in the case of a
participant registered for the ParticipantCompletion protocol."
(although, personally, I find the ambiguity is significantly lessened
by the use of brackets since it leaves the first clause standing as
much more definitive).
P. 41 6.2.1 Note
This note is misleading as the interfaces located in package
com.arjuna.wst are still present but they are not the same interfaces
since they belong to the 1.0 implementation and have a very slightly
different definition. It would be better to say
"The corresponding participant interfaces used in the 1.0 protocol
implementation are located in package <code>com.arjuna.wst</code>."
P. 42 6.2.2 Deploying Participants
This section was almost completely incoherent when it was first
written, addressing problems which would only exist in the mind of an
XTS implementor. Although you made a valiant attempt I don't think
your edits have really made what little it was saying that much
clearer, even given the large scope for improvement, but they have
made it mercifully shorter. I think this needs replacing with
something expressing what actually needs to be said.
"Transactional web services and transactional clients are deployed by
placing them in the application server deploy directory alongside the
XTS service archive (SAR). The SAR exports all the client and web
service API classes needed to manage transactions and enroll and
manage participant web services. It provides implementations of all
the WS-C and WS-T coordination services, not just the coordinator
services. In particular, this it exposes the client and web service
participant endpoints which are needed to receive incoming messages
originating from the coordinator."
"Normally, a transactional application client and the transaction web
service it invokes will be deployed in different application
servers. As long as the XTS SAR is deployed to each of these
containers XTS will transparently route coordination messages from
clients or web services to their coordinator and vice versa. When the
the client begins a transaction by default it creates a context using
the coordination services in its local container. The context holds a
reference to the local Registration Service which means that any web
services enlisted in the transaction enrol with the cooridnation
services in the same container."
"The coordinator does not need to reside in the same container as the
client application. By configuring the client deployment appropriately
it is possible to use the coordinator services co-located with one of
the web services or even to use services deployed in a separate,
dedicated container. See Chapter 8 Stand-Alone Coordination for
details of how to configure a coordinator located in a different
container to the client."
P. 42 6.2.2. Note
This stands as is except that the second occurence of 'were' in the
1st sentence is redundant.
P. 44. 7.1.2 Note
Same issue as for P. 41 6.2.1 Note
P. 44 7.1.3 UserTransaction 1st para 1st sentence
"com.arjuna.mw.wst11.UserTransaction is the class that clients or
services typically employ"
That really ought to just say "clients" rather than "clients or
services" as web services rarely, if ever, start transactions.
By the same token it would probably be best to add at the start of
7.1.5 TransactionManager
"com.arjuna.mw.wst11.TransactionManager is the class that web
services typically employ"
P. 44 userTransaction Methods begin Parameters timeout
First, a general comment. It is conventional to list parameters before
exceptions since knowing what the parameters are is often necessary in
order to understand the possible exceptions but never the other way
round. So, this re-ordering should apply to all the following section.
Secondly, this is not quite the right explanation.
"This optional parameter, measured in milliseconds, specifies a time
interval after which the newly created transaction may be
automatically rolled back by the coordinator"
P. 44 userTransaction Methods commit
The second sentence does not really make sense since execute is not an
appropriate verb to use in the context of a protocol. It would be
better to say
"Volatile2PC and Durable2PC participants enlisted in the transaction
are requested first to prepare and then to commit their changes. If
any of the participants fails to prepare in the first phase then all
other participants are requested to abort."
P. 44 userTransaction Methods commit Exceptions TransactionRolledBackException
This explanation does not make sense.
"The transaction was rolled back either because of a timeout or
because a participant was unable to commit."
P. 45 TransactionManager
"service-side user" is not the best choice of words here. Better would
be just to say "web service" or "transactional web service".
P. 45 TransactionManager Methods resume
The Exceptions list here should be preceded by a Parameters subhead
with a single parameter.
"txContext
A TxContext instance as returned by suspend identifying the
transaction to be resumed."
Also, WrongStateException is not applicable as an exception for this
method. It looks like this has got mangled as it and the explanation
for it being thrown are appropriate to the two enlist methods which
follow on p 46.
P. 46 TransactionManager Methods enlistForVolatile/DurableTwoPhase
There appears to be a dangling Parameters subhead above these two
methods and missing Parameters/Exceptions subheads after each method
description.
Terminology?! The method name used here is enlist but the verb used up
to now has been enroll. Perhaps we should change enroll globally to
enlist? (both terms are perfectly acceptable transactions-speak). If
we stick with enroll then the text here should say enroll even though
the method name uses enlist.
The Parameters section for enlistForVolatileTwoPhase should say
"participant
An implementation of interface Volatile2PCParticipant whose prepare,
commit and abort methods are called when the corresponding coordinator
message is received.
id
A unique identifier for the participant. The value of this String
should differ for each enlisted participant. It should also be
possible for a given identifier to determine that the participant
belongs to the enlisting web service rather than some other web
service deployed to the same container."
The Parameters section for enlistForDurableTwoPhase should say
"participant
An implementation of interface Durable2PCParticipant whose prepare,
commit and abort methods are called when the corresponding coordinator
message is received.
id
A unique identifier for the participant. The value of this String
should differ for each enlisted participant. It should also be
possible for a given identifier to determine that the participant
belongs to the enlisting web service rather than some other web
service deployed to the same container."
The Exceptions section for these two methods is the same
"UnknownTransactionException
No transaction is associated with the invoking thread.
WrongStateException
The transaction is not in a state where new participants may be
enrolled (e.g. it is terminating)"
P. 46 7.2.1
Same issue as for P. 41 6.2.1 Note
P. 46 7.2.2 UserBusinessActivity 1st para 1st sentence
"com.arjuna.wst11.UserBusinessActivity is the class that most clients
or services typically employ"
That really ought to just say "clients" rather than "clients or
services" as web services rarely, if ever, start transactions.
By the same token it would probably be best to add at the start of
7.2.4 BusinessActivityManager
"com.arjuna.mw.wst11.BusinessActivityManager is the class that web
services typically employ"
P. 46 7.2.2 UserBusinessActivity 1st para 2nd sentence
"A client begins a new atomic transaction first obtaining a
UserBusinessActivity from the UserBusinessActivityFactory."
That should say "a new business activity by first..." rather than "a
new atomic transaction by first...".
P. 46 7.2.2 UserBusinessActivity Methods close
Once again the second sentence tries to "execute" a protocol whicch
makes no sense. Also, it is the wrong protocol! Better replace this
with:
"First, all Coordinator Completion participants enlisted in the
activity are requested to complete the activity. Next all
participants, whether they enlisted for Coordinator or Participant
Completion, are requested to close the activity. If any of the
Coordinator Completion participants fails to complete at the first
stage then all completed participants are asked to compensate the
activity while any remaining uncompleted participants are requested to
cancel the activity."
TransactionRolledBackException should probably say a little more
"The activity has been cancelled because one of the Coordinator
Completion participants failed to complete. This exception may also
thrown if one of the Participant Completion participants has not
completed before the client calls close."
P. 46 7.2.2 UserBusinessActivity Methods cancel
The description is somewhat lacking.
"Terminates the business activity. All Participant Completion
participants enlisted in the activity which have already completed are
requested to compensate the activity. All uncompleted Participant
Completion participants and all Coordinator Completion participants
are requested to cancel the activity."
The paragraph about Coordinator Completion participants which follows
the exceptions for cancel is redundant (it's also incorrect). The
complete method has been deprecated and so it should not be
documented.
P. 47 BusinessActivityManager
"service-side user"
This is the same issue as P. 45 TransactionManager above
p 47 BusinessActivityManager Methods currentTransaction
missing 't' in currentTransaction
p 47 BusinessActivityManager Methods resume
This should have a Parameters subhead subhead defining one parameter
"txContext
A TxContext instance as returned by suspend identifying the
transaction to be resumed."
Also, the Exceptions section is incorrect. WrongStateException is not
thrown by resume.
Finally, the enlist methods which follow have suffered the sam efate
as htose for TransactionManager. They should not be preceded by a
Parameters subhead. They should each have a Parameters and Exceptions
subhead following the method description. We ar ealso up against teh
enlist enroll terminology problem again. The text should be:
"enlistForBusinessAgreementWithParticipantCompletion
Enroll the specified participant with current business activity,
causing it to participate in the
BusinessAgreementWithParticipantCompletion protocol. A unique
identifier for the participant is also required.
The return value is an instance of BAParticipantManager which can be
used to notify the coordinator of changes in the participant state. In
particular, since the participant is enlisted for the Participant
Completion protcol it is expected to call the completed method of this
returned instance when it has completed all the work it expects to do
in this activity and has made all its changes permanent.
Alternatively, if the participant does not need to perform any
compensation actions should some other participant fail it can leave
the activity by calling the exit method of the returned
BAParticipantManager instance.
Parameters
participant
An implementation of interface
BusinessAgreementWithParticipantCompletionParticipant whose close,
cancel and compensate methods are called when the corresponding
coordinator message is received.
id
A unique identifier for the participant. The value of this String
should differ for each enlisted participant. It should also be
possible for a given identifier to determine that the participant
belongs to the enlisting web service rather than some other web
service deployed to the same container.
UnknownTransactionException
No transaction is associated with the invoking thread.
WrongStateException
The transaction is not in a state where new participants may be
enrolled (e.g. it is terminating)"
enlistForBusinessAgreementWithCoordinatorCompletion
Enroll the specified participant with current business activity,
causing it to participate in the
BusinessAgreementWithCoordinatorCompletion protocol. A unique
identifier for the participant is also required.
The return value is an instance of BAParticipantManager which can be
used to notify the coordinator of changes in the participant state.
Note that in this case it is an error to call the completed method of
this returned instance. With the Coordinator Completion protocol the
participant is expected to wait until its completed method is called
before it makes all its changes permanent. Alternatively, if the
participant determiens that it has no changes to make it can leave the
activity by calling the exit method of the returned
BAParticipantManager instance.
Parameters
participant
An implementation of interface
BusinessAgreementWithCoordinatorCompletionParticipant whose completed,
close, cancel and compensate methods are called when the corresponding
coordinator message is received.
id
A unique identifier for the participant. The value of this String
should differ for each enlisted participant. It should also be
possible for a given identifier to determine that the participant
belongs to the enlisting web service rather than some other web
service deployed to the same container.
UnknownTransactionException
No transaction is associated with the invoking thread.
WrongStateException
The transaction is not in a state where new participants may be
enrolled (e.g. it is terminating)"
P 49 8.1 Introduction
This should document the release as ocnaitning only the 1.1
implementation.
"The XTS service is deployed as a JBoss service archive (SAR). The
version of the service archive provided with the Transaction Service
implements the 1.1 versions of the WS-C, WS-AT and WS-BA protocols.
You can rebuild the XTS service archive to include both the 1.0 and
1.1 implementations and deploy them side by side. See the service
archive build script for for further details."
p 49 8.2 Table 8.1
The 2nd column should have heading "Property", not parameter.
The entry in the Format column is screwed up and unreadable. This
appears to be because the entries in the parameter column are
overflowing.
P. 50 8.3 The XTS Service Archive
This should have been explained at 6.2.2 where it is appropriate to
talk about it (see the amendements above which provide this
explanation). The text here is not relevant to Stand-Alone
Coordination so this section should be deleted.
P 51 Participant Crash Recovery WS-AT/BA Transaction
You have split three sentences into two paragraphs with sub-heads
here. However, the second sentence under the WSBA subhead "On rare
occasions ... report transaction failures" applies to both protocols.
This should appear below the two indented paragraphs at body text
level to make it clear it is a rider to both of them.
P. 52 1st new para 2st sentence
missing "are"
"... imply that they are ready to ..."
P. 53 Example 9.1
There should be some white space indentation before the method
declaration (i.e. preceding the text "byte[]"), preferably two spaces
in a fixed width code font.
P. 54 9.1.2.1.2 Recovering Participants at Reboot 2nd sentence
"Registration is performed using the XTSATRecoveryManager class
defined in the org.jboss.jbossts.xts.recovery.participant.at."
There are two terminology issues here which also apply to quite a few
subsequent occurences. Firstly, it is normal to say "in class XXX",
not "the XXX class". The latter sounds distinctly odd to a programmer.
Secondly, and much more importantly, you need to use the word
"package" when you speak about a class's location.
Java employs a hierarchical namespace for classes. The spaces in the
hierarchy are called 'packages'. Classes which share the same prefix
up to the last '.' in their full name belong to the same package and
the prefix without the last '.' is used to name this package. Classes
whose prefixes differ are in different packages. So, class
org.my.foo.Foo and class org.my.foo.Foo2 are both in package
org.my.foo while class org.my.foo.bar.Bar and org.my.baz.Baz are in
different packages, org.my.foo.bar and org.my.baz. So this text ought
to say
"Registration is performed using class XTSATRecoveryManager
defined in package org.jboss.jbossts.xts.recovery.participant.at"
Oh, now there's a problem. The full stop at the end of the sentence
should not be conflated as being part of the package name. Myabe
suitable typography can make this clear.
P. 54 Example 9.2
There should be the same white space indentation before each method
declaration, preferably two spaces in a fixed width code font. The
throws clause should be on a newline indented twice as much (ie. 4
spaces).
p 54 2nd to last para
I originally wrote
"The XTS implementation does not know which participants belong to
which recovery modules. ..."
You edited this to
"The XTS implementation does not map participants to recovery
modules. ..."
I understand that you may want to depersonify the code here, removing
the suggestion of psychic attributes, but this translation is
potentially confusing since "map" is a somewhat 'oversignified' term
in computer la-la-land. Perhaps this would be clearer.
"The XTS implementation cannot identify which participants belong to
which recovery modules. This is the responsibility of the recovery
module. ..."
P. 55 WS-BA Coordinator Crash Recovery 2nd para 1st sentence
missing "nor"
"The coordinator does not need to account for any close messages sent
before the crash, nor resend messages if it crashes several times."
P. 55 9.2.2 WS-BA Participant Crash Recovery
All the text is missing here!
P. 56 9.2.3.1. Saving Participant Recovery State 2nd para after Example 9.4
This mentions "PersistableATParticipant" but it should mention
"PersistableBAParticipant"
P 57 9.2.3.2 2nd para
Same error as previous
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
More information about the jbossts-issues
mailing list