JAXB-Facets

JAXB-Facets

News
2012/12/13: We have forked a new version of JAXB-Facets on github: https://github.com/whummer/jaxb-facets. Please pull the most recent version directly from github. Future versions will not be provided for download on this page!
Support JAXB-Facets

Please consider a small donation for continued support and maintenance of JAXB-Facets.

Motivation and General Information
The Java Java Architecture for XML Binding (JAXB, JSR222) is a framework which simplifies the mapping between Java objects and their XML representation. Although an often requested feature, the JAXB reference implementation (JAXB RI, http://jaxb.java.net/) currently does not support XSD facets for simple types (e.g., pattern, maxSize, fractionDigits etc.) in generated XML Schema files. We therefore provide a simple extension to JAXB RI to define facets for Java class attributes using an @Facets annotation, which are then considered in the the XML Schema generation procedure. Furthermore, our implementation supports @MinOccurs and @MaxOccurs annotations. More recently, support has also been added for the annotation XSD element (documentation, appinfo). These features are particularly useful when implementing Web services with JAX-WS (Java API for XML Web Services, JSR224, JAX-WS RI), as illustrated in the example code of an imaginative chart Web service below:
	@XmlRootElement
	@Annotation(id = "anno123", documentation={
		@Documentation(value="Create Chart", lang="en", source="http://...")
	})
	@AppInfo("Charting Web Service")
	public class ChartRequest {
		@Documentation(value="Supported Chart Type")
		public static enum ChartType { line, bar, pie }
		@XmlElement(required=true)
		public ChartType type;
		@MinOccurs(1) @MaxOccurs(10)
		@Facets(minInclusive=-100, maxInclusive=100)
		public List<Integer> value;
		@Facets(pattern="[a-z][a-z0-9]{0,4}")
		public String name;
	}

	@WebService
	public class ChartService {
		public String generateChart(ChartRequest request) {
			// generate some chart image
		}
	}
      
Upon deployment of the ChartService with JAX-WS, the generated WSDL file describing the service interface will contain an XSD declaration similar to the code snippet below:
     <complexType name="chartRequest">
	 <annotation id="anno123">
	  <documentation xml:lang="en" source="http://...">
	   Create Chart
	  </documentation>
	  <appinfo>
	   Charting Web Service
	  </appinfo>
	 </annotation>
	 <sequence>
	  <element name="type">
	   <simpleType>
	    <xs:annotation>
	     <xs:documentation>
	      Supported Chart Type
	     </xs:documentation>
	    </xs:annotation>
	    <restriction base="string">
	     <enumeration value="line" />
	     <enumeration value="bar" />
	     <enumeration value="pie" />
	    </restriction>
	   </simpleType>
	  </element>
	  <element name="value" minOccurs="1" maxOccurs="10">
	   <simpleType>
	    <restriction base="int">
	     <minInclusive value="-100" />
	     <maxInclusive value="100" />
	    </restriction>
	   </simpleType>
	  </element>
	  <element name="name">
	   <simpleType>
	    <restriction base="string">
	     <pattern value="[a-z][a-z0-9]{0,4}" />
	    </restriction>
	   </simpleType>
	  </element>
	 </sequence>
	</complexType>
      
Download
The implementation (source code and compiled class files) can be downloaded here. Please refer to the README.txt for installation/usage instructions.

2012-11-09: version 1.0 (Minor bug fixes and API changes in @Facets. The type of minInclusive/maxInclusive/minExclusive/maxExclusive has been changed from long to String, which is needed, e.g., to represent min/max for dates. This version is not API compatible with 0.x versions!)

2012-09-05: version 0.4 (Support for xsd:annotation, xsd:appinfo, and xsd:documentation)

2012-05-27: version 0.3 (fixed classloading-related issues; ready for deployment in JBoss)

2012-04-15: version 0.2 (supports Facets for XML attributes; support for Java 1.7)

2011-12-04: version 0.1 (initial release)

Maven Users

JAXB-Facets can be easily integrated into your Maven project. Simply add the following entries to your pom.xml file.

Java 1.7
Because JRE 1.7 ships with built-in support for JAXB (in <jre>/lib/rt.jar), we need to tell the JVM how to integrate JAXB-Facets and override the default implementation. One way to achieve this is the Java endorsed standards override mechanism (basically, by setting the system property "java.endorsed.dirs"). In the code below, simply replace "at.ac.tuwien.infosys.jaxb.test.FacetsTestUtil" with the name of the class you want to execute in your project and then run "mvn exec:exec".
<project>
	...
	<dependencies>
		<dependency>
		    <groupId>at.ac.tuwien.infosys</groupId>
		    <artifactId>jaxb-facets</artifactId>
		    <version>0.4</version>
		</dependency>
		...
	</dependencies>

	</repositories>
		...
		<repository>
			<id>infosys-repo</id>
			<name>infosys-repo</name>
			<url>https://www.infosys.tuwien.ac.at/mvn/</url>
		</repository>
	</repositories>
	
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>2.12</version>
				<configuration>
					<argLine>-Djava.endorsed.dirs="${settings.localRepository}/at/ac/tuwien/infosys/jaxb-facets/0.4/"</argLine>
				</configuration>
			</plugin>
			<plugin>
				<groupId>org.codehaus.mojo</groupId>
				<artifactId>exec-maven-plugin</artifactId>
				<version>1.2.1</version>
				<executions>
					<execution>
						<goals>
							<goal>exec</goal>
						</goals>
					</execution>
				</executions>
				<configuration>
					<executable>java</executable>
					<arguments>
						<argument>-Djava.endorsed.dirs=${settings.localRepository}/at/ac/tuwien/infosys/jaxb-facets/0.4/</argument>
						<argument>-classpath</argument>
						<classpath/>
						<argument>at.ac.tuwien.infosys.jaxb.test.FacetsTestUtil</argument>
					</arguments>
				</configuration>
			</plugin>
			...
		</plugins>
		...
	</build>
</project>
Java 1.6 and below
<project>
	...
	<dependencies>
		
		<dependency>
		    <groupId>at.ac.tuwien.infosys</groupId>
		    <artifactId>jaxb-facets</artifactId>
		    <version>0.1</version>
		</dependency>
		...
		<dependency>
			<groupId>com.sun.xml.bind</groupId>
			<artifactId>jaxb-impl</artifactId>
			<version>2.2.4</version>
		</dependency>
		...
	</dependencies>

	</repositories>
		...
		<repository>
			<id>infosys-repo</id>
			<name>infosys-repo</name>
			<url>https://www.infosys.tuwien.ac.at/mvn/</url>
		</repository>
	</repositories>

</project>
JBoss Users
To use JAXB-Facets with JBoss application server (tested with version 5.1.0.GA), put the following files into the $JBOSS_HOME/lib/endorsed directory:

jaxb-api-X.Y.Z.jar (tested with versions 2.2.3 and 2.2.6)

jaxb-impl-X.Y.Z.jar (tested with versions 2.2.4 and 2.2.5)

latest version of JAXB-Facets (jaxb-facets-X.Y.jar)
Acknowledgements

Thanks to Yossi Cohen (yossi2cohen <at> gmail.com) for providing test cases and suggestions for improvement (and for his efforts to push JAXB-Facets into JAXB).

Thanks to Jason Pell (jasonmpell <at> gmail.com) for providing test cases and code improvements.

Thanks to Uwe Maurer for providing test cases.