Java JAXB

A Java binding for the cansas1d:1.1 standard has been auto-created using the JAXB tools from Oracle (formerly Sun, see below for more on JAXB) using the cansas1d.xsd XML Schema. See the Downloading section below.

Using the Java Binding

The basics of the binding are these java statements. First, associate a JAXB context with the canSAS namespace URI

jc = JAXBContext.newInstance("org.cansas.cansas1d");

Next, create an object to read XML data into Java data objects created by JAXB from the canSAS XML Schema.

Unmarshaller unmarshaller = jc.createUnmarshaller();

Next, open an XML file from local storage.

InputStream in = new FileInputStream("a/data/file.xml);

Next, load the XML data into a Java data structure

xmlJavaData = (JAXBElement<SASrootType>) unmarshaller.unmarshal(in);

Next, get the SASroot object

SASrootType sasroot = xmlJavaData.getValue();

With a SASroot object, one can iterate over the SASentry groups and, for instance, print the Title string:

for ( SASentryType entry : sasroot.getSASentry() ) {
        System.out.printf("SASentry Title:  %s\n", entry.getTitle());
}

Full example

An example that uses the binding is provided in the java support and is available for direct download or may be viewed using a web browser: http://www.cansas.org/trac/browser/1dwg/trunk/java/ant-eclipse/src/org/cansas/cansas1d/demo/Reader.java

Output from Reader.java is:

class: org.cansas.cansas1d.demo.Reader
SVN ID: $Id: binding-java-jaxb.rst 332 2013-04-12 16:54:45Z prjemian $


File: ./resources/cansas1d/cs_collagen.xml
SASentry elements: 1
SASentry
Title:  dry chick collagen, d = 673 A, 6531 eV, X6B
#Runs:  1
Run@name:
Run:    Sep 19 1994     01:41:02 am
#SASdata:       1
SASdata@name:
#points:        125

the end.


File: ./resources/cansas1d/1998spheres.xml
SASentry elements: 2
SASentry
Title:  255 nm PS spheres
#Runs:  1
Run@name:
Run:    scan2.dat, scan 5
#SASdata:       1
SASdata@name:
#points:        1824

SASentry
Title:  460 nm PS spheres
#Runs:  1
Run@name:
Run:    scan1.dat, scan 67
#SASdata:       1
SASdata@name:
#points:        3689

the end.


File: cannot_find_this.xml
File not found: cannot_find_this.xml

example: how to retrieve \(I(Q)\)

This is a slightly longer example. Look near line 75 for this code:

SASdataType sasdata = sasroot.getSASentry().getSASdata()
// ...
Qsas[i] = sasdata.getIdata().get(i).getQ().getValue();
Isas[i] = sasdata.getIdata().get(i).getI().getValue();

to see the operations that unwind the data into usable double[] vectors. Pretty straightforward although there is lots of interesting, yet unnecessary, diagnostic output. Here is a table that describes the items in the line just shown:

java item	description
sasdata	SASdataType object
getIdata()	amongst the /SASdata/Idata tuples ...
get(i)	... pick the Idata tuple from row i.
getQ()	Just the /SASdata/Idata/Q
getValue()	and specifically the value, not the unit

Downloading

Resources (JAR files and documentation) for the Java binding may be found in the canSAS subversion Software repositories (for cansas1d:1.1 standard).

cansas1d-#.#.jar

JAR file to add to your CLASSPATH in order to use this binding. Adheres to canSAS 1D standard version #.#.

cansas1d-#.#-javadoc.jar

http://www.cansas.org/svn/1dwg/tags/v#.#/java/cansas1d-#.#-javadoc.jar

Use this JAR file if you want to add the source code documentation as tooltips to your editor, such as eclipse. Note that this file is compatible with any ZIP program and can be unzipped to provide a directory with all the documentation as a set of HTML pages. Start with the index.html page. Adheres to canSAS 1D standard version #.#.

cansas1d-#.#-sources.jar

JAR file of the source code. Note that this is just the source code tree and not the full project development tree for the Java (JAXB) API. Adheres to canSAS 1D standard version #.#.

source code (for developers)

http://www.cansas.org/trac/browser/1dwg/trunk/java/ant-eclipse

canSAS Development project subversion repository for the Java binding. Only use this if you want to participate as a code developer of this binding.

JAXB: Questions and Answers

Q:

What is JAXB?

A:

Java Architecture for XML Binding (http://java.sun.com/developer/technicalArticles/WebServices/jaxb)

Q:

Wow! Is it available for other languages?

A:

Ask Google. JAXB is for Java. (http://java.sun.com/developer/technicalArticles/WebServices/jaxb)

For example: http://www.devx.com/ibm/Article/20261

Q:How do I pull out the \(I(Q)\) data? A:See Java code fragment above Q:Has JAXB been useful? A:Very useful. Since an XML Schema was defined, JAXB was very useful to create a Java binding automatically. Then, javadoc was able to auto-generate the basic documentation as HTML and pdfdoclet was able to auto-generate the documentation in a PDF file.

(re)building the JAXB code

The Java bindings can be built from the XML Schema file using JAXB. For more information, refer to the JAXB documentation: [1]

[1]	JAXB: http://docs.oracle.com/cd/E17802_01/webservices/webservices/docs/2.0/tutorial/doc/JAXBUsing.html

Note

To use xjc, you need a JDK, not just a JVM or JRE.

Starting from the <trunk> directory, create a directory (if necessary) for the JAXB Java source code that will be created from the XML Schema:

mkdir -p java/ant-eclipse/src

Staying in the <trunk> directory, build the JAXB JAXB Java source code:

xjc -d java/ant-eclipse/src cansas1d.xsd -p org.cansas.cansas1d

Next, moving into the Java project directory, rebuild the .jar files:

cd java/ant-eclipse
ant rebuild
/bin/cp dist/*.jar ../