Errata for the Java Common Annotations and API spec

On behalf of BEA Systems, I hereby contribute the following suggested errata for the SCA Java Common Annotations and API Specification.

The line numbers and section numbers are based on the corresponding input specification for this TC.

Michael Rowley

1. Line Numbering starts on the Title Page

The line numbering of the specification starts on the Title Page. It should start at the first line of normative text following the Table of Contents.

2. Typo

On line 488: Change "@EndConveration" to "@EndsConversation"

3. Remove @Remotable from example classes (it is only valid on interfaces)

Delete @Remotable annotation on lines 1942 and 1960.

4. Remove section 1.8.4 for @Conversation

Delete section 1.8.4. It defines an @Conversation annotation that was left over from earlier drafts (the @Conversational and @ConversationAttributes annotations are defined for conversations).

5. Resolve contradiction regarding ConversationEndedException

Description: Section 1.6.2.2 @EndsConversation (lines 409-420) states that when a method is called on a conversational interface after an @EndsConversation has been called, a ConversationEndedException is thrown. This contradicts section 1.6.5 Conversation Lifetime Summary / Ending conversations, lines 494-495, where it states that "after an @EndsConversation method has been called" (on a service reference) ", then a new conversation will automatically be started." ...and... (lines 498-499) if the conversation has timed out, a ConversationEndedException is thrown.

Solution: Replace lines 417-420 at the end of section 1.6.2.2 with the following: "If a conversation is ended with an explicit outbound call to an @EndsConversation method or a call to ServiceReference.endConversation(), then any subsequent call to an operation on the service reference will start a new conversation. If the conversation ends for any other reason (e.g. a timeout occurred), then until ServiceReference.getConversation().end() is called, the ConversationEndedException will be thrown by any conversational operation."

6. Clarify representation of unwired references.

At the end of section "1.8.14 @Reference" add the following paragraph.

At runtime, the representation of an unwired reference will depend on the reference's multiplicity. An unwired reference with a multiplicity of 0..1 must be null. An unwired reference with a multiplicity of 0..N must be an empty array or collection.

7. @Scope annotations may only be used on classes, not interfaces.

Replace the sentence on lines 1584-1585 with the following: "The @Scope annotation type is may only be used on a service's implementation class. It is an error to use this annotation on an interface."

Delete the example in lines 1592-1603.

8. Note the assumption of @Scope("Conversation") in example in section 1.6.7.1.

Problem: The text at line 567 says "Because the service is conversation scoped", but does not show the actual @Scope("CONVERSATION") declaration.

Fix: Change the sentence on line 567 to start with "If the service is conversation scoped".

9. Fix return type of RequestContext.getCallbackReference()

It should be CallableReference<CB> not CallbackReference<CB>. So, line 861 should read:
<CB> CallableReference<CB> getCallbackReference();

10. Clarify usage of @OneWay on classes

The sentence on line 1913 should have the words "or class" inserted so that it reads:

"The @OneWay annotation type is used to annotate a Java interface or class method"

11. Clarification of conversational callback interfaces

An extra @Conversational annotation should be added after the @Remotable annotation on line 558.

Also, the following sentences should be added after line 568:

"When an interface and its callback interface are both marked as conversational, then there is only one conversation that applies in both directions and has the same lifetime. In this case, if both interfaces declare a @ConversationAttributes annotation, then only the annotation on the main interface applies."

12. Clarifying Java to WSDL Mapping Rules.

The current wording of section 1.9 of the Java API specification says:

The SCA Client and Implementation Model for Java applies the WSDL to Java and Java to WSDL mapping rules as defined by the JAX-WS specification [4] for generating remotable Java interfaces from WSDL portTypes and vice versa.
For the mapping from Java types to XML schema types SCA supports both the SDO 2.0 [2] mapping and the JAXB [3] mapping.

This should be replaced with the following:

The SCA Client and Implementation Model for Java applies the WSDL to Java and Java to WSDL mapping rules as defined by the JAX-WS specification [4] for generating remotable Java interfaces from WSDL portTypes and vice versa.
For the purposes of the Java-to-WSDL mapping algorithm, the interface is treated as if it had a @WebService annotation on the class, even if it doesn't, and the org.osoa.OneWay annotation should be treated as a synonym for javax.jws.OneWay. For the WSDL-to-Java, the generated @WebService annotation should imply that the interface is @Remotable.
For the mapping from Java types to XML schema types SCA supports both the SDO 2.1 [2] mapping and the JAXB [3] mapping. Having a choice of binding technologies is allowed, as noted in the first paragraph of section 5 of the JSR 181 (version 2) specification, which is referenced by the JAX-WS specification.

13. Any type that extends Collection means property is multi-valued

Insert the words "any type that extends or implements" before "java.util.Collection" at line 1369, so it reads:

If the property is defined as an array or as any type that extends or implements java.util.Collection, then the implied component type has a property with a many attribute set to true.

sca-j message