COSMOS Design 216809

Line up JAX-WS annotations and management annotations in ME

This is the design document for bugzilla 216809.

Workload Estimation

Name:	Date:	Revised Sections:
Joel Hawkins	3/12/2008	Initial version

Rough workload estimate in person weeks

Process	Sizing	Names of people doing the work
Design	1	Joel
Code	2	Joel
Test	1	Joel/Hubert/QA
Documentation	2	Joel/Rich
Build and infrastructure	0
Code review, etc.*	0
TOTAL	6.0

Terminologies/Acronyms

The terminologies/acronyms below can be used throughout this document.

Note: These definitions are not meant to be general definitions of these terms, but rather refer to how the terms are used within this design document as applied to COSMOS.

Term	Definition
JAX-WS	The Java WebServices API specified by JSRs 224 and 181

Purpose

Axis2 provides an implementation of JAX-WS, which provides a library of annotations for web services. COSMOS code has been using annotations that Joel contributed to the project. The "COSMOS annotations" are oriented towards management interfaces. Despite the difference, there may be annotations that have similar purposes, and can be reconciled. This enhancement is for "lining up" the two set of annotations, and use the JAX-WS standard where possible.

Use Cases

The following have been identified as use cases related to this enhancement.

1. Developer binds a statefull (instance) provider
   There are two variations on this use case:
   1. Data manager is being created from scratch.
      This is addressed in Creating a new Data Manager project.
   2. Data manager is being adapted to existing data source.
      This is the case where the user imports an MDR into Eclipse. Users will create a normal Eclipse project, and then based on the config.properties and domainEPR.xml files, new manifest editor pages will be displayed for editing these. See Updating Data Manager Project.
2. Developer binds a stateless (singleton) provider.
   This is addressed in Deployment.

Detailed Design

The code for this enhancement will be part of the Management Enablement project. The code will span multiple plug-ins. Both J2EE and OSGi deployments will be supported.

• org.eclipse.cosmos.me.management.common - base annotation definitions and utility classes
• org.eclipse.cosmos.me.management.webservices - contains the JAX-WS specific code. This plug-in will have a dependency on an external provider of the JAX-WS annotation classes.

The programming model for COSMOS centers around the concepts of state and composition. COSMOS managed objects are currently exposed as instances, and these instances expose operations and properties as parts of distinct capabilities.

JAX-WS, on the other hand, centers around the concept of stateless interfaces. A large part of the reconcilliation effort resides in mapping JAX-WS's descriptive characteristics onto the COSMOS statefull composition model.

Resource/Type-Level annotations

ManagedResource
	ManagedResource --- ManagedResource (Substitute WebService, WebServiceProvider)
	                    ManagedAdvertisement (Optional), 
	                    ManagedState (Optional), 
	                    ManagedReferece (Optional)

ManagedResourceCapability --- ManagedResourceCapability (Substitute WebService, WebServiceProvider)

ComposableManagedCapabilitySet --- Untouched. No substitute

Honored JAX-WS annotations
	SOAPBinding - verify that this must match Muse expectations - fail the bind and log otherwise
	BindingType - verify that this must match Muse expectations - fail the bind and log otherwise
	RequestWrapper - may be useful for some operations...TBD 
	ResponseWrapper - may be useful for some operations...TBD 
	ServiceMode - verify that this must match Muse expectations - fail the bind and log otherwise
	WebFault - may be useful for some operations...TBD

Method-Level annotations

ManagedResourceFactory --- Deprecate. Use JAX-WS singleton semantics instead
CreateManagedRelation --- Untouched. No substitute
DestroyManagedRelation --- Untouched. No substitute.
ManagedPropertyGetter --- Untouched. No substitute. 
ManagedPropertySetter --- Untouched. No substitute.
ManagedEvent --- Untouched. No substitute.
ManagedEventConsumer --- Untouched. No substitute.

ManagedOperation
	ManagedOperation --- ManagedOperation(Substitute WebMethod)
	

Honored JAX-WS annotations
	Oneway - invalid for COSMOS - fail the bind and log
	WebResult 
	SOAPBinding - verify that this must match Muse expectations - fail the bind and log otherwise
	WebEndpoint - TBD
	

Parameter-Level annotations

ManagedParameter --- (Substitute WebParam) TBD - using JAXB or Muse serialization. 
ManagedEventSource --- Untouched. No substitute.
ManagedEventSituation --- Untouched. No substitute

Resource Level Annotation Mapping

The base annotation for COSMOS components is the ManagedResource interface. This interfaces is currently used as a tagging interface to identify a component implementation's suitability for management under COSMOS.

Managed Resource

/**
 * Annotation used to indicate a class to be exposed as a manageable resource. 
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface ManagedResource {
	/**
	 * A text description of the resource. This value will be used as the
	 * default description when the resource is introspected.
	 */
	String description() default "";
	/**
	 * The namespace of the resource. This namespace will be used for all
	 * operations and properties exposed by this resource (unless overridden) 
	 * that are not part of some other capability  
	 */
	String namespace() default "";
	/**
	 * The desired persistence model for the resource.   
	 */
	String persistent() default "never";
	
	/**
	 * If true, indicates that the resource should support advertisement, and
	 * that the initial advertisementConsumer should be honored.   
	 */
	boolean advertise() default false;
	/**
	 * A text string used by the management host to identify the
	 * endpoint of an initial advertisement. This attribute is only used
	 * if advertise is true.   
	 */
	String advertisementConsumer() default "";
	
	/**
	 * A name used to supply a target for AutoWire-annotated
	 * fields in other managed components.
	 */
	String autowireName() default "";
	
}

The JAX-WS analogs to ManagedResource are WebService and WebServiceProvider

@Retention(value=RetentionPolicy.RUNTIME)
@Target({TYPE})public 
@interface WebService {
    String name() default "";
    String targetNamespace() default "";
    String serviceName() default "";
    String wsdlLocation() default "";
    String endpointInterface() default "";
    String portName() default "";
}

/**
 * Used to annotate a Provider implementation class.
 *
 * @since JAX-WS 2.0
 * @see javax.xml.ws.Provider
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface WebServiceProvider {
    /**
     * Location of the WSDL description for the service.
     */
    String wsdlLocation() default "";
    /**
     * Service name.
     */
    String serviceName() default "";
    /**
     * Target namespace for the service
     */
    String targetNamespace() default "";
    /**
     * Port name.
     */    
    String portName() default "";
}

ManagedResource as it is currently constituted enapsulates a number of concerns:

• Tagging (identifying a resource as one that COSMOS can manage)
• Namespace (WSDL identity)
• State (persistence handling)
• LifeCycle (advertisement)
• Reference handling (autowiring)

These concerns will be seperated into different annotations as follows:

ManagedResource

/**
 * Annotation used to indicate a class to be exposed as a manageable resource. 
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface ManagedResource {
    /**
     * Service name.
     */
    String serviceName() default "";
    /**
     * Target namespace for the service
     */
    String targetNamespace() default "";
}

JAX-WS Replacement WebService or WebServiceProvider can completely replace ManagedResource

ManagedState

/**
 * Annotation used to indicate a class to be exposed as a manageable resource. 
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface ManagedState {
	/**
	 * The desired persistence model for the resource.   
	 */
	String persistent() default "never";
}

ManagedAdvertisement

/**
 * Annotation used to indicate a class to be exposed as a manageable resource. 
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface ManagedAdvertisement {
	/**
	 * If true, indicates that the resource should support advertisement, and
	 * that the initial advertisementConsumer should be honored.   
	 */
	boolean advertise() default false;
	/**
	 * A text string used by the management host to identify the
	 * endpoint of an initial advertisement. This attribute is only used
	 * if advertise is true.   
	 */
	String advertisementConsumer() default "";
	
}

ManagedReference

/**
 * Annotation used to indicate a class to be exposed as a manageable resource. 
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface ManagedReference {
	/**
	 * A name used to supply a target for AutoWire-annotated
	 * fields in other managed components.
	 */
	String autowireName();
	
}

Contribution Manager Modifications

Convert to opt-in. Process common annotations.

WebServices Binding Implementation

Define precedence order for annotations Define failure cases (seen above).

UI workflows

There are no UI implications for this enhancement.

Deployment (OSGi)

This approach is TBD.

Task Breakdown

Required tasks:

1. Axis2 bundle updates to supply JAX-WS imports
2. Modification of ContributionManager to support Binding opt-in approach.
3. WSDL management.
4. JUnits to test opt-in.
5. Update WSRF and WSDM capability implementations to use JAX-WS
6. Create a me.management.webservices component to handle binding management targets with JAX-WS annotations
7. JUnits to JAX-WS scenarios.
8. Deprecate me.management.wsdm and replace all of the current annotated components in COSMOS with JAX-WS annotations

Open Issues/Questions

IPZilla for Axis2 Security requirement interactions

All reviewer feedback should go in the Talk page for 216809.