Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

Main Page

Serializer

MetadataSerializer is responsible for serializing and deserializing OpenmrsObjects. It is build upon XStream library and uses XML format. It is able to produce a list of metadata with all related items and a package header that contains information such as name, description, creation date, OpenMRS version. They are stored in two separate files called metadata.xml and header.xml and packaged in a zip file.

You can implement the writeReplace/readResolve methods in your shareable class if you want to provide a custom serialization. It needs to conform standard rules specified in the Java documentation. You can use it to provide extra dependencies for your object which you need to export together with your object. Typically it is not needed since all fields of your object will be examined and references to other objects resolved and serialized as well. However, you will need to define an extra field for dependencies and initialize it in the writeReplace method, if you reference objects in xmls or other text formats.

You may also consider implementing void onSave(Map<OpenmrsObject, OpenmrsObject> incomingToExisting). This method will be called by the Metadata Sharing module on your object upon importing. The map parameter contains a map with keys pointing to items included in the package and values pointing to existing items that should be used instead by your object. Typically, you will use the map to replace all incoming uuids with existing uuids in xmls and other text formats. It is not needed to replace Java references in your object since they will be replaced by the Metadata Sharing module automatically.

You can see a reference implementation of this mechanism in HTML Form Entry Module under HTML-184.

Handler

Handler is an interface that can be implemented to support different kinds of metadata. A custom handler can be registered in HandlerFactory. There is ConceptHandler that provides support for org.openmrs.Concept. Apart from that there are OpenmrsMetadataHandler and OpenmrsObjectHandler. They provide with just a basic support for classes implementing OpenmrsMetadata and OpenmrsObject. OpenmrsMetadataHandler in particular determines at runtime a list of classes on the classpath that can be exported.

Publish/subscribe protocol 

A published package is accessible through a URL which consists of 5 parts:

  1. URL prefix - specifies the way the server can be accessed through the Internet and the application context path. This is typically http://localhost:8080/openmrs in development and http://example.com/openmrs in production.
  2. /ws/rest/metadatasharing/package/  to follow OpenMRS REST patterns
  3. UUID of the package group (a mutual UUID along all package versions)
  4. /latest which indicates that the subscriber will lookup for the latest version from the package group
  5. (optional) .form suffix required on OpenMRS versions which do not support web services. Note: after upgrading OpenMRS from e.g. 1.6.x to 1.8.1+, the publish URLs lose this suffix, but old URLs remain accessible. 

Example of a publish URL: http:/localhost:8080/openmrs/ws/rest/metadatasharing/package/7f2d4731-0a98-4118-8fe0-d4b9731986c6/latest

Example of a curl to this URL 

<subscriptionHeader id="1">
    <packageHeader id="2" uuid="874f1efb-d73e-4093-9dd9-6e532be3a6fe">
        <dateCreated id="3">2011-08-18 00:30:45</dateCreated>
        <name>Roles</name>
        <description>All available roles</description>
        <openmrsVersion>1.8.2 Build 21762</openmrsVersion>
        <version>5</version>
        <group>7f2d4731-0a98-4118-8fe0-d4b9731986c6</group>
    </packageHeader>
    <contentUri id="4">../7f2d4731-0a98-4118-8fe0-d4b9731986c6/5/download</contentUri>
</subscriptionHeader>

The packageHeader node contains all header information about the package. 

The contentUri node is a relative URI to the place where we can download zipped package with all metadata. 

The download URL is similar to publish URL, but it ends with: %VERSION/download. This allows us to download any published version of the package, but this feature is not used yet. 

Fetching packages on the fly via the metadata REST webservice

The module provides a REST web service exposing an API. Currently, only one operation is provided i.e to fetch a package from a remote server, both GET or POST are supported.

Packages can be fetched either programmatically or by entering the appropriate url with the expected request parameters in the browser and your will get the download prompt. Packages can be fetched as plain text or as a zip file.

Request Parameters: (* denotes required parameter)

  • key - Required if server has it defined.* *This must be acquired in advance from the admin of the remote server in case it is required
  • type - Required. This is the fully-qualified class name of the type of object you wish to export
  • uuids - This is a comma-separated list of uuids to export (you may specify either uuids, ids, or both)
  • ids - This is a comma-separated list of ids to export (you may specify either uuids, ids, or both)
  • compress - Optional. If set to "true", this will export the file as a metadata zip package. Otherwise as raw xml.
  • modifiedSince - (Date format = dd/mm/yyyy) When specified, items to be returned should have had created or modifications after the specified date

URL Format:

[server:url]/ws/module/metadatasharing/getMetadata?&[requestParameters]

Example of the URL

http://localhost:8080/openmrs/ws/module/metadatasharing/getMetadata?&type=org.openmrs.Location&ids=1&ids=2&uuids=5b635b8d02812d2e1c97691cd71fc05a&modifiedSince=01/01/2012
  • No labels