180 likes | 304 Views
ACS Course Data entities and XML serialization. H. Sommer. obj.getFoo(). Logik. Subsystem2. Value Objects. value object. remote object. transportby value. obj.getFoo(). Subsystem1. fine-grained remote calls degrade performance; more runtime coupling among computers.
E N D
ACS CourseData entities and XML serialization H. Sommer ESO - Garching 23 June – 02 July, 2003
obj.getFoo() Logik Subsystem2 Value Objects value object remote object transportby value obj.getFoo() Subsystem1 • fine-grained remote calls degrade performance; • more runtime coupling among computers ALMA 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. ALMA 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. ALMA Common Software course
Definition a2 a3 b2 a1 reference by ID a4 ref_b1 b1 b3 XML Doc 1 schema A imports schema B 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 ALMA Common Software course
CommonEntity.xsdmodule “define” <!-- a handle to reference another entity --> <xsd:complexTypename="EntityRefT"> <xsd:attributename="entityId"type="ent:EntityIdT"use="required"/> <!-- name of the root element of the entity, usually same as schema name --> <xsd:attributename="entityTypeName"type="ent:EntityTypeNameT"use="required"/> <!-- version --> <xsd:attributename="documentVersion"type="xsd:string"use="required"/> </xsd:complexType> ALMA Common Software course
CommonEntity.xsdmodule “define” <!-- common to all entities --> <xsd:complexTypename="EntityT"> <xsd:attributename="entityId"type="ent:EntityIdT"use="required"/> <!-- used by container and archive to make messing with IDs harder --> <xsd:attributename="entityIdEncrypted"type="xsd:string"use="required"/> <!-- name of the root element, usually same as schema name --> <xsd:attributename="entityTypeName"type="ent:EntityTypeNameT"use="required"/> <!-- version of the schema that the entity object complies with --> <xsd:attributename="schemaVersion"type="xsd:string"use="required"/> <!-- version, managed by the archive on "store/update" --> <xsd:attributename="documentVersion"type="xsd:string"/> </xsd:complexType> ALMA Common Software course
Schema Snippet <xsd:elementname="SchedBlock"> <xsd:complexType> <xsd:complexContent> <xsd:extensionbase="prj:ObsUnitT"> <xsd:sequence> <xsd:elementname="SchedBlockEntity"type="sbl:SchedBlockEntityT"/> <xsd:elementname="ObsProjectRef"type="prj:ObsProjectRefT"/> <xsd:elementname="SchedBlockImaging"type="prj:ImagingProcedureT"/> <xsd:elementname="ObsProcedure"type="sbl:ObsProcedureT"/> <xsd:elementname="ObsTarget"type="sbl:TargetT"maxOccurs="unbounded"/> <xsd:elementname="PhaseCalTarget"type="sbl:TargetT"minOccurs="0” maxOccurs="unbounded"/> <xsd:elementname="PointingCalTarget"type="sbl:TargetT"minOccurs="0” maxOccurs="unbounded"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> </xsd:element> ALMA Common Software course
Definition Details (1)copiedfrom 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). ALMA 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. ALMA 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. ALMA 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 ALMA Common Software course
Scheduling Block binding class packagealma.entity.xmlbinding.schedblock; publicclassSchedBlockextendsalma.entity.xmlbinding.obsproject.ObsUnitTimplementsjava.io.Serializable { // just a few of the generated methods publicvoidaddObsTarget(TargetTvObsTarget) {…} publicjava.util.EnumerationenumerateObsTarget() {…} publicalma.entity.xmlbinding.obsproject.ImagingProcedureTgetSchedBlockImaging() {…} } ALMA Common Software course
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; }; ALMA Common Software course
Utility Classes from (jcont) alma.acs.entityutil EntitySerializer ObsProposalobsProp=…; // this is your entity object XmlEntityStructentStruct=null; EntitySerializerentSer=EntitySerializer.getEntitySerializer(myLogger); // more comfortable... entStruct=entSer.serializeEntity(obsProp); // perhaps faster... entStruct=entSer.serializeEntity(obsProp,obsProp.getObsProposalEntity()); ALMA Common Software course
Utility Classes from (jcont) alma.acs.entityutil EntityDeserializer EntityDeserializerentDes=newEntityDeserializer(myLogger); ObsProposal obsProp2 = (ObsProposal) entDes.deserializeEntity(entStruct,ObsProposal.class); ALMA 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=newEntityRefFinder(true); ObsProjectproj=getObsProject(); EntityRefT[]refs=m_entityRefFinder.findEntityReferences(proj); ALMA 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 = 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) ALMA Common Software course