Introduction

This project is developed for Java programmers who would like to use JAXB to work with XML schemas defined by the Open Geospatial Consortium, Inc (OGC).

The OGC Schemas project compile all (well, almost all) of the OGC Schemas with JAXB RI schema compiler in order to make them usable in Java GIS environments via JAXB. Beyond that this project also provides useful tools for working with GIS-related XML documents.

See also Project Goals document.

As a Java GIS developer you might be interested in the following deliverables of this project:

• OGC Schemas project compiles most of the OGC Schemas. You may use the generated (schema-derived in JAXB terminology) classes to work with OGC specs-conforming XML documents via JAXB (parse/unmarshal, serialize/marshal, validate).
  • If you've decided to use schema-derived classes, you may also benefit from further tools implemented in the frame of this project (for instance, [GML-JTS converter]).
• If generated classes do not fit your requirements for some reason, you may reuse JAXB binding (*.xjb) files from this project and compile schemas of interest on your own.

Using the generated classes

Generated classes are ready for use with JAXB; you only need to add the schema artifact (JAR file) into your classpath and create a JAXB context.

Adding schema artifact into the classpath

With Maven

If you're using Maven you normally only need to add the schema artifact into dependencies. For instance for WMS 1.3.0 schema you'll have:

<dependency>
	<groupId>org.jvnet.ogc</groupId>
	<artifactId>wms-v_1_3_0-schema</artifactId>
	<version>1.0.0</version>
</dependency>

• org.jvnet.ogc - group id of the OGC Schema project (same for all the artifacts).
• wms-v_1_3_0-schema - artifact id for the target schema (WMS 1.3.0).
• 1.0.0 - version of the OGC Schema project (same for all the artifacts). Note that this version has nothing to do with actual schema version (like WMS 1.3.0 or GML 3.1.1).

Artifact ids of schema artifacts are formed according to the following pattern:

schema-schemaVersion-schema

The schema part comes from the lowercase schema specification abbreviature (wms for Web Map Service - WMS). The schemaVersion comes from the actual schema version (v_1_3_0 for WMS 1.3.0).

Artifacts of the OGC Schemas project are distributed via the dev.java.net Maven2 repository so make sure to add this repo into the project/repositories of your pom.xml:

<project ...>
	...
	<repositories>
		...
		<repository>
			<id>maven2-repository.dev.java.net</id>
			<url>http://download.java.net/maven/2</url>
		</repository>
		...
	</repositories>
	...
</project>

Without Maven

If you're not using Maven, you will need to download and deploy the JAR files manualy. You can download the desired files directly from the dev.java.net Maven2 repository or get all of them in a single ZIP distribution from the Releases page.

When you have the files, make sure to add the schema-schemaVersion-schema-version.jar (ex. wms-v_1_3_0-schema-1.0.0.jar for WMS 1.3.0) files to the classpath. In some cases you will also need to add dependencies of the given schema JAR (Maven resolves dependencies automatically). Please see the [schema dependencies] document.

Creating JAXB context

In order to create a JAXB context you'll typically need to pass so-called context path to the JAXBContext.newInstance(...) method:

JAXBContext context = JAXBContext.newInstance("net.opengis.wms.v_1_3_0");

If you only have one schema to process, context path is the package name of the target schema. It is formed according to the following pattern:

net.opengis.schema.schemaVersion (compare to net.opengis.wms.v_1_3_0)

If you process several schemas within a single JAXB context, context path will be colon-delimited package names of schema packages:

JAXBContext context = JAXBContext.newInstance("net.opengis.filter.v_1_1_0:net.opengis.gml.v_3_1_1");

Unmarshalling

Below is a code fragment which demonstrates unmarshalling functionality. This code make a GetCapabilities request to the Demins WorldMap WMS server and lists names of the offered layers.

// Create JAXB context for WMS 1.3.0
JAXBContext context = JAXBContext
		.newInstance("net.opengis.wms.v_1_3_0");

// Use the created JAXB context to construct an unmarshaller
Unmarshaller unmarshaller = context.createUnmarshaller();

// GetCapabilities URL of the Demis WorldMap WMS Server
String url = "http://www2.demis.nl/wms/wms.asp?REQUEST=GetCapabilities&VERSION=1.3.0&wms=WorldMap";

// Unmarshal the given URL, retrieve WMSCapabilities element
JAXBElement<WMSCapabilities> wmsCapabilitiesElement = unmarshaller
		.unmarshal(new StreamSource(url), WMSCapabilities.class);

// Retrieve WMSCapabilities instance
WMSCapabilities wmsCapabilities = wmsCapabilitiesElement.getValue();

// Iterate over layers, print out layer names
for (Layer layer : wmsCapabilities.getCapability().getLayer()
		.getLayer()) {
	System.out.println(layer.getName());
}

Marshalling

// Construct the WMS capabilities object
WMSCapabilities wmsCapabilities = ...;

// Create a JAXB context
JAXBContext context = JAXBContext
		.newInstance("net.opengis.wms.v_1_3_0");

// Create a marshaller
Marshaller marshaller = context.createMarshaller();

// Set a property for the formatted (indented) output
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);

// Marshal capabilities to the system out
marshaller.marshal(wmsCapabilities, System.out);

Validating

All the OGC schemas are included in JARs and therefore are available as classpath resources. This allows using schemas in the runtime for validation:

// Create JAXB context for WMS 1.3.0
JAXBContext context = JAXBContext
	.newInstance("net.opengis.wms.v_1_3_0");

// Use the created JAXB context to construct an unmarshaller
Unmarshaller unmarshaller = context.createUnmarshaller();

// Create an XML schema factory
SchemaFactory schemaFactory = SchemaFactory
	.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);

// Get the WMS 1.3.0 classpath resource URL
URL schemaURL = getClass().getClassLoader().getResource(
	"wms/1.3.0/capabilities_1_3_0.xsd");

// Create an XML schema instance
Schema schema = schemaFactory.newSchema(schemaURL);

// Use the created XML schema instance for validation during
// unmarshalling
unmarshaller.setSchema(schema);

// Unmarshaller is now a validating unmarshaller

You can also validate on marshal:

SchemaFactory schemaFactory = SchemaFactory
	.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);

URL schemaURL = getClass().getClassLoader().getResource(
	"wms/1.3.0/capabilities_1_3_0.xsd");

Schema schema = schemaFactory.newSchema(schemaURL);

marshaller.setSchema(schema);

Working with schema-derived object structures

Schema-derived classes are just normal POJOs (well, almoust), you can work with them as with any other value classes. It is, however, recommended to use the generated ObjectFactory for object instantiation. Below is a fragment of code which create a WMS capabilities response:

private net.opengis.wms.v_1_3_0.ObjectFactory objectFactory =
	new net.opengis.wms.v_1_3_0.ObjectFactory();

private WMSCapabilities createWMSCapabilities() {
	final WMSCapabilities wmsCapabilities = objectFactory
			.createWMSCapabilities();

	wmsCapabilities.setService(createService());
	wmsCapabilities.setCapability(createCapability());

	return wmsCapabilities;
}

private Service createService() {
	final Service service = objectFactory.createService();
	service.setName("WMS");
	service.setTitle("Dummy WMS service");
	service.setOnlineResource(createOnlineResource("http://localhost"));
	return service;
}

private Capability createCapability() {
	final Capability capability = objectFactory.createCapability();
	capability.setRequest(createRequest());
	capability.setException(createException());
	capability.setLayer(createLayer());
	return capability;
}

// And so on

You can see the whole example here.