ACS Course Data entities and XML serialization H

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

Value Objects ALMA Project value object remote object transport by value obj. get. Foo() obj. g et. Foo Subsystem 1 () Logik Subsystem 2 • fine-grained remote calls degrade performance; • more runtime coupling among computers 19. November 2002 2

What kind of data ? ALMA Project • • Only hierarchical object data, e. g. “User”, “Observing. Project”, “Correlator. Config” (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. 19. November 2002 3

Why XML ? ALMA Project 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. 19. November 2002 4

Definition ALMA Project a 2 a 3 a 1 a 4 ref_b 1 b 2 reference b 1 by ID XML Doc 1 schema A imports schema B b 3 XML Doc 2 schema B • 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 19. November 2002 5

Common. Entity. xsd module “define” ALMA Project <!-- a handle to reference another entity --> <xsd: complex. Type name="Entity. Ref. T"> <xsd: attribute name="entity. Id" type="ent: Entity. Id. T" use="required"/> <!-- name of the root element of the entity, usually same as schema name --> <xsd: attribute name="entity. Type. Name" type="ent: Entity. Type. Name. T" use="required"/> <!-- version --> <xsd: attribute name="document. Version" type="xsd: string" use="required"/> </xsd: complex. Type> 19. November 2002 6

Common. Entity. xsd module “define” ALMA Project <!-- common to all entities --> <xsd: complex. Type name="Entity. T"> <xsd: attribute name="entity. Id" type="ent: Entity. Id. T" use="required"/> <!-- used by container and archive to make messing with IDs harder --> <xsd: attribute name="entity. Id. Encrypted" type="xsd: string" use="required"/> <!-- name of the root element, usually same as schema name --> <xsd: attribute name="entity. Type. Name" type="ent: Entity. Type. Name. T" use="required"/> <!-- version of the schema that the entity object complies with --> <xsd: attribute name="schema. Version" type="xsd: string" use="required"/> <!-- version, managed by the archive on "store/update" --> <xsd: attribute name="document. Version" type="xsd: string"/> </xsd: complex. Type> 19. November 2002 7

Schema Snippet <xsd: element name="Sched. Block"> ALMA Project <xsd: complex. Type> <xsd: complex. Content> <xsd: extension base="prj: Obs. Unit. T"> <xsd: sequence> <xsd: element name="Sched. Block. Entity" type="sbl: Sched. Block. Entity. T"/> <xsd: element name="Obs. Project. Ref" type="prj: Obs. Project. Ref. T"/> <xsd: element name="Sched. Block. Imaging" type="prj: Imaging. Procedure. T"/> <xsd: element name="Obs. Procedure" type="sbl: Obs. Procedure. T"/> <xsd: element name="Obs. Target" type="sbl: Target. T" max. Occurs="unbounded"/> <xsd: element name="Phase. Cal. Target" type="sbl: Target. T" min. Occurs="0” max. Occurs="unbounded"/> <xsd: element name="Pointing. Cal. Target" type="sbl: Target. T" min. Occurs="0” max. Occurs="unbounded"/> </xsd: sequence> </xsd: extension> </xsd: complex. Content> </xsd: complex. Type> </xsd: element> 19. November 2002 8

Definition Details (1) copied from the Java comp. tutorial ALMA Project • 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>/<schema. Name>” (e. g. “Alma/Obs. Prep/Sched. Block”). • XML schemas consist of “elements” and “types”. Names of schema types must end with a “T”, like in <xsd: complex. Type name="Obs. Unit. T">. This avoids problems with generating binding classes (e. g. alma. mypackage. Obs. Unit. T), and makes it easier to find a name for a wrapper class that adds functionality to such a binding class (e. g. alma. mywrappers. Obs. Unit). 19. November 2002 9

Definition Details (2) ALMA Project • Top-level entities are defined as the root elements in the schema files, like Obs. Project or Sched. Block. To store administrational data like ID, version etc. , they must each have a child element of type Entity. T (defined in the ACS module “define”/idl/Common. Entity. xsd, xml namespace “Alma/Common. Entity”). For example, in the schema file Obs. Project. xsd, the schema element Obs. Project has a child of type Obs. Project. Entity. T, which itself is of type Entity. T. Perhaps it would have been more intuitive to use an inheritance convention instead of inclusion (Sched. Block could inherit from Entity. T), 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 Sched. Block. xsd we see that in fact our schema element “Sched. Block” inherits from Obs. Unit. T, which would not have been possible otherwise. 19. November 2002 10

Definition Details (3) ALMA Project • 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) Entity. Ref. T, which declared in the schema file Common. Entity. xsd (module ACS/…/define). For example, a Sched. Block references the Obs. Project to which it belongs. The schema element Sched. Block has a child element Obs. Project. Ref whose type inherits from Entity. Ref. T. Therefore, an XML document for a Sched. Block entity can reference another XML document that is an Obs. Project. 19. November 2002 11

Java Binding Classes ALMA Project • 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 19. November 2002 12

Scheduling Block binding class ALMA Project package alma. entity. xmlbinding. schedblock; public class Sched. Block extends alma. entity. xmlbinding. obsproject. Obs. Unit. T implements java. io. Serializable { // just a few of the generated methods public void add. Obs. Target(Target. T v. Obs. Target) {…} public java. util. Enumeration enumerate. Obs. Target() {…} public alma. entity. xmlbinding. obsproject. Imaging. Procedure. T get. Sched. Block. Imaging() {…} } 19. November 2002 13

Transport over CORBA in Java it will be nicer… ALMA Project From Module ACS/LGPL/Common. Software/define, xmlentity. idl struct Xml. Entity. Struct { string xml. String; string entity. Id; string entity. Type. Name; // unique name like "Sched. Block" string schema. Version; }; 19. November 2002 14

Utility Classes from (jcont) alma. acs. entityutil ALMA Project Entity. Serializer Obs. Proposal obs. Prop = …; // this is your entity object Xml. Entity. Struct ent. Struct = null; Entity. Serializer ent. Ser = Entity. Serializer. get. Entity. Serializer(my. Logger); // more comfortable. . . ent. Struct = ent. Ser. serialize. Entity(obs. Prop); // perhaps faster. . . ent. Struct = ent. Ser. serialize. Entity(obs. Prop, obs. Prop. get. Obs. Proposal. Entity()); 19. November 2002 15

Utility Classes from (jcont) alma. acs. entityutil ALMA Project Entity. Deserializer ent. Des = new Entity. Deserializer(my. Logger); Obs. Proposal obs. Prop 2 = (Obs. Proposal) ent. Des. deserialize. Entity(ent. Struct, Obs. Proposal. class); 19. November 2002 16

Utility Classes from (jcont) alma. acs. entityutil ALMA Project Entity. Ref. Finder Traverses a tree of binding objects (e. g. starting from an Obs. Project) and collects all references to other entity objects (Entity. Ref. T elements) m_entity. Ref. Finder = new Entity. Ref. Finder(true); Obs. Project proj = get. Obs. Project(); Entity. Ref. T[] refs = m_entity. Ref. Finder. find. Entity. References(proj); 19. November 2002 17

Makefile support ALMA Project • 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/Common. Software/acstestentities/idl/acs. Test. Entities. xml • Define XSDBIND in the Makefile: XSDBIND = acs. Test. Entities 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 acs. Test. Entities. 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) 19. November 2002 18