View source for COSMOS Design 220949

= '''Change History''' =
{|{{BMTableStyle}}
!align="left"|Name:
!align="left"|Date:	
!align="left"|Revised Sections:
|-
|Hubert Leung
|03/04/2008	
|<ul><li>Initial version</li></ul>
|}

= '''	Workload Estimation''' =

{|{{BMTableStyle}}
|+{{BMTableCaptionStyle}}|Rough workload estimate in person weeks
|-{{BMTHStyle}}
! Process
! Sizing	
! Names of people doing the work
|-
| align="left" | Design
| 0.4
| Hubert Leung
|-
| align="left" | Code
| 1.4
| Hubert Leung
|-
| align="left" | Test	
| 0.6
| Hubert Leung
|-
| align="left" | Documentation	
| 0.2
| Hubert Leung
|-
| align="left" | Build and infrastructure
| 0.4
| Saurabh Dravid
|-
| align="left" | Code review, etc.*
|
|
|-
! align="right" | TOTAL
| 3
|
|}

'* -  includes other committer work (e.g. check-in, contribution tracking)

=Purpose=
The current implementation of the data manager framework makes use of the COSMOS annotations and MUSE.  The SOAP message does not follow the document/literal style because there are wrapping elements around the message payload.  We are also using WS-Addressing in the message header.  In order to ensure interoperability of the MDRs with non-COSMOS MDRs and to comply with the CMDBf standard more strictly, we want to support stateless web services in COSMOS.  SOAP messages will not require WS-Addressing and use document/literal payload style.

=Design=
== Technology Stack ==

#Java 5
#Axis2 without JAX-WS
#data binding: use existing binding in org.eclipse.cosmos.dc.cmdbf.services

== Programming model ==

===Framework===
* Generate skeleton and stub from WSDL, with no data binding.  The interface will accept an OMElement and return an OMElement.  The parameter is the payload of the SOAP message, and the return value is the payload of the response message.  OMElement is the object that represent an XML element in the Axiom object model, which can be thought of as an equivalent model as DOM, but it uses streaming XML technology.  
* COSMOS Framework:  The concept of AbstractMdr and AbstractFederatingCMDB will remain.  They will be subclasses of their corresponding skeletons.  However, AbstractFederatingCMDB will not be subclass of AbstractMDR.
* The CMDBf services will have separate EPRs.  Unlike the muse annotation approach, the WSDL is not generated on the fly, and the WSDL of different services is not merged into one WSDL.  For example:
 http://myhost:8080/axis2/services/QueryService
 http://myhost:8080/axis2/services/RegistrationService
* The code for the EPRs for each data manager need to be deployed in the same .aar file and share the same services.xml.  
* WSDL of the services can be retrived by using the axis2 ?wsdl feature.  For example: http://localhost:8080/org.eclipse.cosmos.example.mdr.ws/services/QueryService?wsdl
* Custom APIs:  COSMOS data managers allows developers to create custom APIs.  (such as the logging and stat data manager examples.)  Under the axis2 approach, they will be web services deployed in axis2.  There is no restriction on how they are created.  
* Since there will be more than one EPR for each data manager, we need a way to define the set of endpoints that constitute a data manager.  Axis2 has a feature called service group which is a grouping of services.  (Don't confuse this with WS Service Group standard.)  Services in the same service group can share the same service group context.  Services from more than one data managers can be deployed in the same Axis2 container, but services for each data manager will be in the same group.  It is done by a configuration/deployment file called services.xml.  
* Address registry: The groups of EPRs will be registered at the broker.  Each EPR is identified by their target namespace (e.g. http://cmdbf.org/schema/1-0-0/query).  So from each data manager, the client can get the EPR of the CMDBf query EPR if available.  (I will need to confirm whether this is possible during implementation.)

===Policy===
Metadata is defined as WS-Policy.  Axis2 claim some support of WS-Policy using WS-Commons/Neethi framework.  More research is required to determine if we can leverage their support.  The current code defines the metadata policy in a file.  We can provide a web service operation in data manager web service to return the policy.  But there may be more elegant ways to handle this.

===Tooling===
WTP provides eclipse tooling for axis2.  A "Data manager project" is a dynamic web project.

==Impacts==
# UI: Since the SOAP message payload format will change, UI will need to adapt to the change when parsing SOAP body for data.
# Broker: Affects the way broker and management domain store addresses and properties of data managers.
# Tooling
# Existing exmaple data managers: Port to use the new framework.

== SOAP Message Examples ==
Request:
<pre>
POST /org.eclipse.cosmos.example.mdr.ws/services/QueryService?wsdl HTTP/1.1
Content-Type: text/xml; charset=UTF-8
SOAPAction: ""
User-Agent: Axis2
Host: localhost:8081
Transfer-Encoding: chunked

17f
<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Body>
		<s:query xmlns:s="http://cmdbf.org/schema/1-0-0/datamodel">
			<s:itemTemplate id="items">
				<s:recordConstraint>
					<s:recordType localName="student" namespace="" />
				</s:recordConstraint>
			</s:itemTemplate>
		</s:query>
	</soapenv:Body>
</soapenv:Envelope>
0

</pre>


Response:
<pre>
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 26 Mar 2008 14:37:56 GMT

656
<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Body>
		<cmdbf:queryResult xmlns:cmdbf="http://cmdbf.org/schema/1-0-0/datamodel">
			<cmdbf:nodes templateId="items">
				<cmdbf:item>
					<cmdbf:record xmlns="http://school">
						<student>
							<identity firstName="Mike" lastName="Lee" id="03" />
						</student>
						<cmdbf:recordMetadata>
							<cmdbf:recordId>03</cmdbf:recordId>
						</cmdbf:recordMetadata>
					</cmdbf:record>
					<cmdbf:instanceId>
						<cmdbf:mdrId>org.eclipse.cosmos.samples.cmdbf.XMLRepository
						</cmdbf:mdrId>
						<cmdbf:localId>03</cmdbf:localId>
					</cmdbf:instanceId>
				</cmdbf:item>
				<cmdbf:item>
					<cmdbf:record xmlns="http://school">
						<student>
							<identity firstName="Jane" lastName="Ryerson" id="02" />
						</student>
						<cmdbf:recordMetadata>
							<cmdbf:recordId>02</cmdbf:recordId>
						</cmdbf:recordMetadata>
					</cmdbf:record>
					<cmdbf:instanceId>
						<cmdbf:mdrId>org.eclipse.cosmos.samples.cmdbf.XMLRepository
						</cmdbf:mdrId>
						<cmdbf:localId>02</cmdbf:localId>
					</cmdbf:instanceId>
				</cmdbf:item>
				<cmdbf:item>
					<cmdbf:record xmlns="http://school">
						<student>
							<identity firstName="Bob" lastName="Davidson" id="01" />
						</student>
						<cmdbf:recordMetadata>
							<cmdbf:recordId>01</cmdbf:recordId>
						</cmdbf:recordMetadata>
					</cmdbf:record>
					<cmdbf:instanceId>
						<cmdbf:mdrId>org.eclipse.cosmos.samples.cmdbf.XMLRepository
						</cmdbf:mdrId>
						<cmdbf:localId>01</cmdbf:localId>
					</cmdbf:instanceId>
				</cmdbf:item>
			</cmdbf:nodes>
		</cmdbf:queryResult>
	</soapenv:Body>
</soapenv:Envelope>
0
</pre>

=References=

* [[COSMOS_Axis2_Framework|Document for migrating code to the Axis2 framework]]

=Open Issues/Questions=

All reviewer feedback should go in the [[Talk:COSMOS_Design_220949|Talk page for 220949]].


[[Category:COSMOS_Bugzilla_Designs]]