eso - garching 23 june – 02 july, 2003 acs course data entities and xml serialization h. sommer

ESO - Garching 23 June – 02 July, 2003

ACS CourseACS CourseData entities and Data entities and XML serializationXML serialization

H. Sommer

2

ALMA Project

Garching, 23 June – 02 July 2003

ALMA Common Software course

Value Objects

Subsystem2Logik

obj.getFoo()

Subsystem1

obj.getFoo()

transportby value

value objectremoteobject

• fine-grained remote calls degrade performance; • more runtime coupling among computers

3

ALMA Project



What kind of data ?

• Only hierarchical object data, e.g. “User”, “ObservingProject”, “CorrelatorConfig”(Perhaps a few other data types that are different views on this data.)

• Lists of value objects don’t need to be defined as new value object types; use CORBA sequences of existing value objects instead.

• Simple parameters as IDL data types, not XML

• Bulk data (from correlator, pipelines) transported in binary format, not considered here.

4

ALMA Project



Why XML ?

Using CORBA with multiple programming languages, CORBA valuetypes would be the only alternative standard

Comparison:

• XML can also be used for persistence without writing much extra code

• XML also for non-CORBA-Transport (email, …)

• XML Schema offers more powerful declarations and thus enables automatic validation

• CORBA valuetypes not sufficiently supported by many ORBs

• Can always deal with XML “by hand”. Especially important for early use of ALMA software when specialized editors are not yet available.

5

ALMA Project



Definition

a1a4

a2

XML Doc 1schema A imports schema B

XML Doc 2 schema B

b1

a3

b3

b2

ref_b1reference

by ID

• Partitioning of hierarchical data “nodes” into separate XML schemas

• Referencing

– Within a schema: as a child element

– Across schemas: by ID (soft reference, not enforced by compiler or any other tool – integrity is developer’s responsibility)

– IDs generated by the archive to ensure system-wide uniqueness

6

ALMA Project



CommonEntity.xsdmodule “define”



<xsd:complexType name="EntityRefT">

<xsd:attribute name="entityId" type="ent:EntityIdT" use="required"/>



<xsd:attribute name="entityTypeName" type="ent:EntityTypeNameT" use="required"/>



<xsd:attribute name="documentVersion" type="xsd:string" use="required"/>

</xsd:complexType>

7

ALMA Project



CommonEntity.xsdmodule “define”



<xsd:complexType name="EntityT">

<xsd:attribute name="entityId" type="ent:EntityIdT" use="required"/>



<xsd:attribute name="entityIdEncrypted" type="xsd:string" use="required"/>



<xsd:attribute name="entityTypeName" type="ent:EntityTypeNameT" use="required"/>



<xsd:attribute name="schemaVersion" type="xsd:string" use="required"/>



<xsd:attribute name="documentVersion" type="xsd:string"/>

</xsd:complexType>

8

ALMA Project



Schema Snippet<xsd:element name="SchedBlock">

<xsd:complexType>

<xsd:complexContent>

<xsd:extension base="prj:ObsUnitT">

<xsd:sequence>

<xsd:element name="SchedBlockEntity" type="sbl:SchedBlockEntityT"/>

<xsd:element name="ObsProjectRef" type="prj:ObsProjectRefT"/>

<xsd:element name="SchedBlockImaging" type="prj:ImagingProcedureT"/>

<xsd:element name="ObsProcedure" type="sbl:ObsProcedureT"/>

<xsd:element name="ObsTarget" type="sbl:TargetT" maxOccurs="unbounded"/>

<xsd:element name="PhaseCalTarget" type="sbl:TargetT" minOccurs="0”

maxOccurs="unbounded"/>

<xsd:element name="PointingCalTarget" type="sbl:TargetT" minOccurs="0”

maxOccurs="unbounded"/>

</xsd:sequence>

</xsd:extension>

</xsd:complexContent>

</xsd:complexType>

</xsd:element>

9

ALMA Project



Definition Details (1)copied from the Java comp. tutorial

• XML namespaces: the normal industry convention would be to use an internet URL. This does not work for ALMA since alma.org is not ours. To avoid confusion, the namespace should be “Alma/<subsystem>/<schemaName>” (e.g. “Alma/ObsPrep/SchedBlock”).

• XML schemas consist of “elements” and “types”. Names of schema types must end with a “T”, like in <xsd:complexType name="ObsUnitT">. This avoids problems with generating binding classes (e.g. alma.mypackage.ObsUnitT), and makes it easier to find a name for a wrapper class that adds functionality to such a binding class (e.g. alma.mywrappers.ObsUnit).

10

ALMA Project



Definition Details (2)

• Top-level entities are defined as the root elements in the schema files, like ObsProject or SchedBlock. To store administrational data like ID, version etc., they must each have a child element of type EntityT (defined in the ACS module “define”/idl/CommonEntity.xsd, xml namespace “Alma/CommonEntity”). For example, in the schema file ObsProject.xsd, the schema element ObsProject has a child of type ObsProjectEntityT, which itself is of type EntityT.Perhaps it would have been more intuitive to use an inheritance convention instead of inclusion (SchedBlock could inherit from EntityT), but since XML schema only allows single inheritance, we don’t want to use it up for the sake of the framework. In the file SchedBlock.xsd we see that in fact our schema element “SchedBlock” inherits from ObsUnitT, which would not have been possible otherwise.

11

ALMA Project



Definition Details (3)

• From one entity object (that is, an XML document) you can reference another entity object through the ID. In the schema, this must be declared uniformly using (a subtype of) EntityRefT, which declared in the schema file CommonEntity.xsd (module ACS/…/define). For example, a SchedBlock references the ObsProject to which it belongs. The schema element SchedBlock has a child element ObsProjectRef whose type inherits from EntityRefT. Therefore, an XML document for a SchedBlock entity can reference another XML document that is an ObsProject.

12

ALMA Project



Java Binding Classes

• Java code generated from the XML schemas as part of the software build process

• Typesafe get()/set() methods ensure that version conflicts be noticed at compile time

• Classes contain code for de-/serialization from and to XML

• Classes contain validation code to enforce schema constraints

• Currently the Castor framework is used, JDK’s JAXB considered

13

ALMA Project



Scheduling Block binding class

package alma.entity.xmlbinding.schedblock;

public class SchedBlock extends alma.entity.xmlbinding.obsproject.ObsUnitT implements java.io.Serializable

{

// just a few of the generated methods

public void addObsTarget(TargetT vObsTarget) {…}

public java.util.Enumeration enumerateObsTarget() {…}

public alma.entity.xmlbinding.obsproject.ImagingProcedureT getSchedBlockImaging() {…}

}

14

ALMA Project



Transport over CORBAin Java it will be nicer…

From Module ACS/LGPL/CommonSoftware/define,

xmlentity.idl

struct XmlEntityStruct

{

string xmlString;

string entityId;

string entityTypeName;// unique name like "SchedBlock" string schemaVersion;

};

15

ALMA Project



Utility Classes from (jcont) alma.acs.entityutil

EntitySerializer

ObsProposal obsProp = …; // this is your entity object

XmlEntityStruct entStruct = null;

EntitySerializer entSer = EntitySerializer.getEntitySerializer(myLogger);

// more comfortable...

entStruct = entSer.serializeEntity(obsProp);

// perhaps faster...

entStruct = entSer.serializeEntity(obsProp, obsProp.getObsProposalEntity());

16

ALMA Project




EntityDeserializer

EntityDeserializer entDes = new EntityDeserializer(myLogger);

ObsProposal obsProp2 = (ObsProposal)

entDes.deserializeEntity(entStruct, ObsProposal.class);

17

ALMA Project




EntityRefFinder

Traverses a tree of binding objects (e.g. starting from an ObsProject) and collects all references to other entity objects (EntityRefT elements)

m_entityRefFinder = new EntityRefFinder(true);

ObsProject proj = getObsProject();

EntityRefT[] refs = m_entityRefFinder.findEntityReferences(proj);

18

ALMA Project



Makefile support

• Schemas must go into the module’s idl directory

• XML descriptor file with schema namespace to Java package mapping information must be created in the same directory; for more details, see the Java Component Tutorial section 5.1.3. Example in CVS: ACS/LGPL/CommonSoftware/acstestentities/idl/acsTestEntities.xml

• Define XSDBIND in the Makefile:XSDBIND = acsTestEntitieswith the name of the xml descriptor file mentioned before. This will result in the binding classes generated and compiled into a JAR file, here acsTestEntities.jar

• If your schemas include schemas from other subsystems (or ACS), useXSDBIND_INCLUDE = systementitieswith the xml descriptor of the other module as the value (again without .xml suffix)

eso - garching 23 june – 02 july, 2003 acs course data entities and xml serialization h. sommer

Documents