JAXB namespace configuration

In this blog post I would like to demonstrate how to configure a namespace in the XML messages used by REST endpoints. If you would rather jump right to a working example, have a look on my github account. Let's consider the following example message, where widgets can have different type of resources.

	<?xml version="1.0" encoding="UTF-8"?>
	<bb:widget xmlns:bb="http://www.backbase.com/ns/widgets">
	<bb:resources>
	<bb:resource type="text/css" src="css/wrap-layout.css"/>
	<bb:resource type="text/javascript" src="template/wrap-layout.js"/>
	<bb:resource type="image/png" src="png/wrap-layout.js"/>
	</bb:resources>
	</bb:widget>

view raw widget-config.xml hosted with ❤ by GitHub

In the above example all XML elements belong to the "http://www.backbase.com/ns/widgets" namespace. This simple widget configuration message could have the following XSD:

	<?xml version="1.0" encoding="UTF-8"?>
	<xs:schema elementFormDefault="qualified"
	targetNamespace="http://www.backbase.com/ns/widgets"
	xmlns:bb="http://www.backbase.com/ns/widgets"
	xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<!-- widget definition root element -->
	<xs:element name="widget" type="bb:widgetType"/>
	<!-- widget definition data types -->
	<xs:complexType name="resourcesType">
	<xs:sequence>
	<xs:element type="bb:resourceType" name="resource" maxOccurs="unbounded" minOccurs="1" />
	</xs:sequence>
	</xs:complexType>
	<xs:complexType name="widgetType">
	<xs:sequence>
	<xs:element type="bb:resourcesType" name="resources" />
	</xs:sequence>
	</xs:complexType>
	<xs:complexType name="resourceType">
	<xs:simpleContent>
	<xs:extension base="xs:string">
	<xs:attribute type="xs:string" name="type" use="required"/>
	<xs:attribute type="xs:string" name="src" use="required"/>
	</xs:extension>
	</xs:simpleContent>
	</xs:complexType>
	</xs:schema>

view raw widget-config.xsd hosted with ❤ by GitHub

In order to generate and consume these type of messages we create our model WidgetConfig and WidgetConfigRef.

	@XmlRootElement(name = "widget", namespace = "http://www.backbase.com/ns/widgets")
	@XmlAccessorType(XmlAccessType.FIELD)
	public class WidgetConfig {
	@XmlElementWrapper(name = "resources", namespace = "http://www.backbase.com/ns/widgets")
	@XmlElement(name = "resource", namespace = "http://www.backbase.com/ns/widgets")
	private List<WidgetResourceRef> widgetResourceRefs;
	public WidgetConfig() {
	widgetResourceRefs = new ArrayList<>();
	}
	public void addWidgetResource(WidgetResourceRef widgetResourceRef) {
	widgetResourceRefs.add(widgetResourceRef);
	}
	public List<WidgetResourceRef> getWidgetResourceRefs() {
	return widgetResourceRefs;
	}
	}

view raw WidgetConfig.java hosted with ❤ by GitHub

	@XmlAccessorType(XmlAccessType.FIELD)
	public class WidgetResourceRef {
	@XmlAttribute
	private String type;
	@XmlAttribute
	private String src;
	/** Default constructor, needed for JAXB framework */
	public WidgetResourceRef() {
	}
	public WidgetResourceRef(String type, String src) {
	this.type = type;
	this.src = src;
	}
	public String getType() {
	return type;
	}
	public String getSrc() {
	return src;
	}
	public void setType(String type) {
	this.type = type;
	}
	public void setSrc(String src) {
	this.src = src;
	}
	}

view raw WidgetResourceRef.java hosted with ❤ by GitHub

With the namespace attribute of @XmlRootElement, @XmlElementWrapper and @XmlElement we configure the namespace on all XML elements found in the XSD. Note the use of @XmlElementWrapper, which is used to produce a wrapper XML element around resource elements. In order to set the namespace prefix (in this case "bb") we need the following:

	@XmlSchema(
	xmlns = {
	@XmlNs(prefix = "bb", namespaceURI ="http://www.backbase.com/ns/widgets"),
	},
	elementFormDefault = XmlNsForm.QUALIFIED
	)
	package com.za.jaxb.widget;
	import javax.xml.bind.annotation.XmlNs;
	import javax.xml.bind.annotation.XmlNsForm;
	import javax.xml.bind.annotation.XmlSchema;

view raw package-info.java hosted with ❤ by GitHub

Next we use Spring's excellent Object/XML Mapping support by defining a marshaller/unmarshaller as shown below:

	<?xml version="1.0" encoding="UTF-8"?>
	<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:oxm="http://www.springframework.org/schema/oxm"
	xsi:schemaLocation="http://www.springframework.org/schema/beans
	http://www.springframework.org/schema/beans/spring-beans.xsd
	http://www.springframework.org/schema/oxm
	http://www.springframework.org/schema/oxm/spring-oxm.xsd">
	<oxm:jaxb2-marshaller id="marshaller">
	<oxm:class-to-be-bound name="com.za.jaxb.widget.WidgetConfig" />
	<oxm:class-to-be-bound name="com.za.jaxb.widget.WidgetResourceRef" />
	</oxm:jaxb2-marshaller>
	</beans>

view raw spring-config.xml hosted with ❤ by GitHub

And we are ready. A working example you can find on my github account. Note, if you are still using Java 6, you need to update the JAXB implementation by including the following dependencies. Otherwise the namespace prefixes will not be set. The JAXB implementation in Java 7 hasn't got this issue.

	<dependency>
	<groupId>javax.xml.bind</groupId>
	<artifactId>jaxb-api</artifactId>
	<version>2.2.7</version>
	</dependency>
	<dependency>
	<groupId>com.sun.xml.bind</groupId>
	<artifactId>jaxb-impl</artifactId>
	<version>2.2.7</version>
	</dependency>

view raw pom-with-jaxb.xml hosted with ❤ by GitHub

Playing with distributed percolator from elasticsearch

I have recently attended an elasticsearch meetup in Amsterdam, where I heard the first time about a very cool feature of elasticsearch, called percolator.
Using the percolator, you can register queries against one or multiple indices and then you can send percolate requests with a document which return which registered queries it matched.

The percolator has been available in the product since the version 0.15, however starting from version 1.0 a fully distributed version of percolator will be available. The redesigned percolator will have a _percolator type mapping instead of a _percolator index, and the query and data will coexist with the same index. The redesigned percolator is also fixing the confusing part of the query registration API where the index name was represented as the type in the _percolator index. In the redesigned percolator this confusion is gone, because the _percolator became a type

	curl -XPUT 'http://localhost:9200/households/_percolator/my_id' -d {
	"query": {
	...
	}
	}

view raw request.sh hosted with ❤ by GitHub

There are many use cases for percolator. For example in case or a real estate website, registered users save their preferences (a query) about their dream house which they want to buy. When a new house is added to the website, a notification is sent to the registered users if there is match with their preferences (using percolate requests).
Let's consider the following model

	public class Household {
	private String id;
	private String description;
	private Double lat;
	private Double lon;
	private int price;
	private Date postDate;
	}

view raw Household.java hosted with ❤ by GitHub

Since automatic mapping of "geo enabled" properties has been disabled, you have to provide the correct mapping for geo properties. For the sake of simplicity XContentBuilder, a built-in utility from elasticsearch, is used to construct the JSON representation of the model. Another alternative would be to use Jackson.

	private void addGeoTypeMapping() throws IOException {
	XContentBuilder mapping = jsonBuilder()
	.startObject()
	.startObject("household")
	.startObject("properties")
	.startObject("location")
	.field("type", "geo_point")
	.endObject()
	.endObject()
	.endObject()
	.endObject();
	client.admin().indices().prepareCreate("households")
	.addMapping("household", mapping).execute().actionGet();
	}

view raw PercolateTest.java hosted with ❤ by GitHub

Let's consider that one user is interested in houses within 5km of Utrecht central station prices between 250000 and 300000. We could have the following filter

	private FilterBuilder filterBuilder() {
	return boolFilter()
	.must(rangeFilter("price").from("250000").to("300000"))
	.must(geoDistanceFilter("location")
	.point(52.09, 5.11)
	.distance(5, DistanceUnit.KILOMETERS)
	);
	}

view raw PercolateTest.java hosted with ❤ by GitHub

Using the above filter we can register the following query. The user id is saved in this query, in order to know to which user it belongs.

	client.prepareIndex("households", "_percolator", "myQuery")
	.setSource(jsonBuilder()
	.startObject()
	.field("query", constantScoreQuery(filterBuilder()))
	.field("user_id", "123")
	.endObject())
	.setRefresh(true) // Needed when the query shall be available immediately
	.execute().actionGet();

view raw PercolateTest.java hosted with ❤ by GitHub

When a new house is added then we can a send percolate request with the new document. Note that the new document is not added to the index.

	// create a source of the percolate request
	XContentBuilder docBuilder = jsonBuilder()
	.startObject()
	.field("doc")
	.startObject()
	.startObject("location")
	.field("lat", 52.10)
	.field("lon", 5.12)
	.endObject()
	.field("price", 290000)
	.endObject()
	.endObject();
	// send the percolate request
	PercolateResponse response = client.preparePercolate()
	.setIndices("households")
	.setDocumentType("household")
	.setSource(docBuilder)
	.execute().actionGet();
	assertThat(response.getCount(), is(1L));

view raw PercolateTest.java hosted with ❤ by GitHub

If there was a match we need to check to which user the query belongs in order to send notification.

	GetResponse matchedQuery = client.prepareGet("households","_percolator", "myQuery")
	.setFetchSource("user_id", "query")
	.execute().actionGet();
	assertThat(((String) matchedQuery.getSource().get("user_id")), is("123"));
	assertThat(matchedQuery.getSource().get("query"), is(nullValue()));

view raw PercolateTest.java hosted with ❤ by GitHub

A working example you find on my github account. In order to try it, you need to clone elasticsearch and build it locally, since the redesigned percolator will be available in the 1.0 release.

Modularising Spring's Java-based configuration

When using Spring's XML based configuration it is a good approach to modularise the configuration with the <import/> element. For example with a JPA repository configuration there can be an infrastructure configuration for setting up the LocalContainerEntityManagerFactoryBean and JpaTransactionManager

	<?xml version="1.0" encoding="UTF-8"?>
	<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:jdbc="http://www.springframework.org/schema/jdbc"
	xsi:schemaLocation="http://www.springframework.org/schema/jdbc http://www.springframework.org/schema/jdbc/spring-jdbc.xsd
	http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
	<bean id="entityManagerFactory"
	class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
	<property name="dataSource" ref="dataSource"/>
	<property name="jpaVendorAdapter">
	<bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter">
	<property name="generateDdl" value="true"/>
	<property name="database" value="H2"/>
	</bean>
	</property>
	<property name="packagesToScan" value="com.za.spring.fun" />
	</bean>
	<bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager">
	<property name="entityManagerFactory" ref="entityManagerFactory"/>
	</bean>
	<jdbc:embedded-database id="dataSource" type="H2"/>
	</beans>

view raw infrastructure-config.xml hosted with ❤ by GitHub

Using the above, not application specific configuration, we can create an application specific repository configuration

	<?xml version="1.0" encoding="UTF-8"?>
	<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:jpa="http://www.springframework.org/schema/data/jpa"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/data/jpa http://www.springframework.org/schema/data/jpa/spring-jpa.xsd">
	<import resource="infrastructure-config.xml"/>
	<jpa:repositories base-package="com.za.spring.fun.repository"/>
	</beans>

view raw repository-config.xml hosted with ❤ by GitHub

The above modularisation can be easily achieved also using Spring's Java-based configuration. The @Import annotation can import other configuration classes.

	package com.za.spring.fun.config;
	import org.springframework.context.annotation.Configuration;
	import org.springframework.context.annotation.Import;
	import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
	/**
	* Java based repository configuration.
	*
	* @author Zoltan Altfatter
	*/
	@Configuration
	@Import(InfrastructureConfig.class)
	@EnableJpaRepositories("com.za.spring.fun.repository")
	public class RepositoryConfig {
	}

view raw RepositoryConfig.java hosted with ❤ by GitHub

Besides @Import, the @ImportResource can be used to import configuration from XML files. You can mix the XML and Java configuration this way, although I do not recommend doing that. Similar to using XML or Java for DI configuration the my recommendation is that together with your team you decide which approach to use and stick to it, otherwise maintenance work will be much more difficult.

	package com.za.spring.fun.mixconfig;
	import org.springframework.context.annotation.Configuration;
	import org.springframework.context.annotation.ImportResource;
	import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
	/**
	* Java and XML based repository configuration.
	*
	* @author Zoltan Altfatter
	*/
	@Configuration
	@ImportResource("config/infrastructure-config.xml")
	@EnableJpaRepositories("com.za.spring.fun.repository")
	public class RepositoryMixConfig {
	}

view raw RepositoryMixConfig.java hosted with ❤ by GitHub

Note that Spring requires CGLIB to support Java configuration classes. Starting from Spring 3.2 explicit dependency on CGLIB is no longer required, because it is repackaged and inlined into the framework.

For a working example you can have a look at my github account.