1. ESO - Garching 23 June – 02 July, 2003 ACS Course Data entities and XML serialization H. Sommer

2. ALMA Project 2Garching, 23 June – 02 July 2003ALMA Common Software course Value Objects Subsystem2 Logik obj.getFoo() Subsystem1 obj.getFoo() transport by value value object remote object fine-grained remote calls degrade performance; more runtime coupling among computers

3. ALMA Project 3Garching, 23 June – 02 July 2003ALMA Common Software course 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 4Garching, 23 June – 02 July 2003ALMA Common Software course 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 5Garching, 23 June – 02 July 2003ALMA Common Software course Definition a1 a4 a2 XML Doc 1 schema A imports schema B XML Doc 2 schema B b1 a3 b3 b2 ref_b1 reference 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 6Garching, 23 June – 02 July 2003ALMA Common Software course CommonEntity.xsd module “define”

7. ALMA Project 7Garching, 23 June – 02 July 2003ALMA Common Software course CommonEntity.xsd module “define”

8. ALMA Project 8Garching, 23 June – 02 July 2003ALMA Common Software course Schema Snippet <xsd:element name="PhaseCalTarget" type="sbl:TargetT" minOccurs="0” maxOccurs="unbounded"/> <xsd:element name="PointingCalTarget" type="sbl:TargetT" minOccurs="0” maxOccurs="unbounded"/>

9. ALMA Project 9Garching, 23 June – 02 July 2003ALMA Common Software course 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/ / ” (e.g. “Alma/ObsPrep/SchedBlock”). XML schemas consist of “elements” and “types”. Names of schema types must end with a “T”, like in. 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 10Garching, 23 June – 02 July 2003ALMA Common Software course 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 11Garching, 23 June – 02 July 2003ALMA Common Software course 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 12Garching, 23 June – 02 July 2003ALMA Common Software course 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 13Garching, 23 June – 02 July 2003ALMA Common Software course 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 14Garching, 23 June – 02 July 2003ALMA Common Software course Transport over CORBA in 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 15Garching, 23 June – 02 July 2003ALMA Common Software course 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 16Garching, 23 June – 02 July 2003ALMA Common Software course Utility Classes from (jcont) alma.acs.entityutil EntityDeserializer EntityDeserializer entDes = new EntityDeserializer(myLogger); ObsProposal obsProp2 = (ObsProposal) entDes.deserializeEntity(entStruct, ObsProposal.class);

17. ALMA Project 17Garching, 23 June – 02 July 2003ALMA Common Software course Utility Classes from (jcont) alma.acs.entityutil 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 18Garching, 23 June – 02 July 2003ALMA Common Software course 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 = acsTestEntities with 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), use XSDBIND_INCLUDE = systementities with the xml descriptor of the other module as the value (again without.xml suffix)