.. $Id: binding-java-jaxb.rst 332 2013-04-12 16:54:45Z prjemian $ .. index:: ! binding; Java JAXB .. _java.jaxb.binding: ================ 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* :index:`XML Schema`. See the :ref:`binding.java.download` 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 .. code-block:: java 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. .. code-block:: java Unmarshaller unmarshaller = jc.createUnmarshaller(); Next, open an XML file from local storage. .. code-block:: java InputStream in = new FileInputStream("a/data/file.xml); Next, load the XML data into a Java data structure .. code-block:: java xmlJavaData = (JAXBElement) unmarshaller.unmarshal(in); Next, get the SASroot object .. code-block:: java SASrootType sasroot = xmlJavaData.getValue(); With a `SASroot` object, one can iterate over the `SASentry` groups and, for instance, print the `Title` string: .. code-block:: java 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:`download <../../java/ant-eclipse/src/org/cansas/cansas1d/demo/Reader.java>` 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 .. index:: I(Q) .. _binding.java.howto.I: example: how to retrieve :math:`I(Q)` ============================================ This is a slightly longer example. Look near line 75 for this code: .. code-block:: java 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 ============== ================================================ .. _binding.java.download: Downloading =========== Resources (JAR files and documentation) for the Java binding may be found in the canSAS subversion :ref:`repository`. *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. .. index:: ! JAXB 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 .. index:: I(Q) :Q: How do I pull out the :math:`I(Q)` data? :A: See Java code fragment :ref:`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: [#]_ .. [#] 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 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 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 ../