source: 1dwg/trunk/doc/source/binding-java-jaxb.rst @ 315

Last change on this file since 315 was 315, checked in by prjemian, 7 years ago

start to update the java binding documentation: show how to built the source files with JAXB

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL
File size: 6.8 KB


.. index:: ! binding; Java JAXB


FIX THIS into a how-to use the JAR file to read canSAS data files

A Java binding for the cansas1d:1.1 standard has been auto-created using the JAXB tools from Sun (see below for more on JAXB) using the cansas1d.xsd :index:`XML Schema`. Resources (JAR files and documentation) for the Java binding may be found in the canSAS subversion repository:

Subversion repository

canSAS subversion repository tagged release directory for the Java binding. Use resources from this directory in your development projects.


JAR file to add to your CLASSPATH in order to use this binding.


Use this JAR file if you want to add the javadoc documentation as tooltips to your editor, such as eclipse. (auto-generated from the project source code using maven2) 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.


JAR file of the source code. (auto-generated from the project source code using maven2) Note that this is just the source code tree and not the full project development tree for the Java (JAXB) API.


PDF file of the javadoc source code documentation. (auto-generated from the project source code using pdfdoclet)

source code (for developers)

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

An example ( has been constructed to show how to read a cansas1d:1.1 XML file using the Java API.

In short, these are the important two lines:

CanSas1dType reader = new CanSas1dType();


SASrootType sasRoot =;

where String xmlFile; is the name of the XML file to be read. You will also need these imports:

.. code-block:: java
        import javax.xml.bind.JAXBException;
        import net.smallangles.cansas1d.CanSas1dType;
        import net.smallangles.cansas1d.SASdataType;
        import net.smallangles.cansas1d.SASentryType;
        import net.smallangles.cansas1d.SASrootType;
        import net.smallangles.cansas1d.SASentryType.Run;

Also, since can throw a JAXBException, you should use a try{} catch {} clause. See the source code for the example.

.. index::
        Java file;
        XML file; 1998spheres.xml

Here is a Java class that shows how to use the JAXB binding. Use this with any of the test data supplied with the cansas-1d-standard directory (above). By default, it shows the two samples in the 1998spheres.xml example file. (


The reader will have to get the directory paths right until this documentation improves.

.. literalinclude:: examples/
   :language: java
.. index:: I(Q)

example: how to retrieve I(Q)

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

Qsas[i] = sdt.getIdata().get(i).getQ().getValue();
Isas[i] = sdt.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
sdt 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
.. index:: Java file;

Since the source code is rather lengthy, download it from:

.. index:: Java file;


java-test.xml is an example cansas1d:1.1 XML data file (derived from the standard test file for the lake desmearing code).

.. literalinclude:: examples/java-test.xml
   :language: xml
.. index:: ! JAXB

JAXB: Questions and Answers


What is JAXB?


Java Architecture for XML Binding (


Wow! Is it available for other languages?


Ask Google. JAXB is for Java. (

For example:

.. index:: I(Q)

How do I pull out the I(Q) data?


See Java code fragment above that gets data for desmearing. (:ref:`java-test.xml`)


Has JAXB been useful?


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

To build the java files with JAXB from the XSD Schema, refer to the JAXB documentation: [1]


Here are the steps taken (this time). Note that to use xjc, you'll need the full JDK, not just a JVM or JRE.

[jemian@gov,250,v1.1]$ mkdir -p java/ant-eclipse/src/org/cansas
[jemian@gov,251,v1.1]$ xjc -d java/ant-eclipse/src/org/cansas cansas1d.xsd
[jemian@gov,262,_1]$ mv *.java ..
[jemian@gov,263,_1]$ cd ../
[jemian@gov,264,cansas1d]$ rmdir _1
edit package line in *.java to read::
        package org.cansas.cansas1d;
Note: See TracBrowser for help on using the repository browser.