Changeset 252 for 1dwg


Ignore:
Timestamp:
Aug 30, 2012 7:35:37 PM (7 years ago)
Author:
prjemian
Message:

refs #24

Location:
1dwg/trunk/doc
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • 1dwg/trunk/doc/source/binding-java-jaxb.rst

    r244 r252  
    11.. $Id$ 
    22 
     3.. index:: ! binding; Java JAXB 
    34 
    45.. _java.jaxb.binding: 
     
    78Java JAXB 
    89================ 
     10 
     11A Java binding for the cansas1d/1.1 standard has been auto-created using the JAXB tools 
     12from Sun (see below for more on JAXB) using the *cansas1d.xsd* :index:`XML Schema`. 
     13Resources (JAR files and documentation) for the Java binding may be found in 
     14the canSAS subversion repository: http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0/java 
     15 
     16Subversion repository 
     17        http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0/java 
     18         
     19        canSAS subversion repository tagged release directory for the Java binding. 
     20        Use resources from this directory in your development projects. 
     21 
     22*cansas1d-1.0.jar* 
     23        http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0/java/cansas1d-1.0.jar 
     24         
     25        JAR file to add to your CLASSPATH in order to use this binding. 
     26 
     27*cansas1d-1.0-javadoc.jar* 
     28        http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0/java/cansas1d-1.0-javadoc.jar 
     29         
     30        Use this JAR file if you want to add the  
     31        javadoc documentation as tooltips to your editor, such as eclipse.  
     32        (auto-generated from the project source code using maven2) 
     33        Note that this file is compatible with any ZIP program and can be unzipped 
     34        to provide a directory with all the documentation as a set of HTML pages. 
     35        Start with the *index.html* page. 
     36 
     37*cansas1d-1.0-sources.jar* 
     38        http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0/java/cansas1d-1.0-sources.jar 
     39         
     40        JAR file of the source code.    
     41        (auto-generated from the project source code using maven2) 
     42        Note that this is *just* 
     43        the source code tree and not the full project development tree 
     44        for the Java (JAXB) API. 
     45 
     46*cansas1d-1.0.pdf* 
     47        http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0/java/cansas1d-1.0.pdf 
     48 
     49        PDF file of the javadoc source code documentation. 
     50        (auto-generated from the project source code using pdfdoclet) 
     51 
     52source code (for developers) 
     53        http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/java/maven/eclipse 
     54         
     55        canSAS Development project subversion repository for the Java binding.   
     56        Only use this if you want to participate as a code developer of this binding. 
     57 
     58 
     59*Example_canSAS_Reader.java*: example usage in JAVA 
     60======================================================= 
     61 
     62An example (*Example_canSAS_Reader.java*) has been constructed 
     63(http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/java/maven/eclipse/src/main/java/org/scatteringsw/reader/Example_canSAS_Reader.java) 
     64to show how to read a cansas1d/1.1 XML file using the Java API.  
     65 
     66In short, these are the important two lines: 
     67 
     68.. code-block:: java 
     69 
     70        CanSas1dType reader = new CanSas1dType(); 
     71 
     72and 
     73 
     74.. code-block:: java 
     75 
     76        SASrootType sasRoot = reader.open(xmlFile); 
     77 
     78where *String xmlFile;* is the name of the XML file to be read.  
     79You will also need these imports: 
     80 
     81.. code-block:: java 
     82        :linenos: 
     83         
     84        import javax.xml.bind.JAXBException; 
     85         
     86        import net.smallangles.cansas1d.CanSas1dType; 
     87        import net.smallangles.cansas1d.SASdataType; 
     88        import net.smallangles.cansas1d.SASentryType; 
     89        import net.smallangles.cansas1d.SASrootType; 
     90        import net.smallangles.cansas1d.SASentryType.Run; 
     91 
     92Also, since *CanSas1dType.open(xmlFile)* can throw a 
     93*JAXBException*, you should use a *try{} catch {}* 
     94clause. See the source code for the example. 
     95 
     96.. index::  
     97        Java file; Example_canSAS_Reader.java 
     98        XML file; 1998spheres.xml 
     99 
     100Here is a Java class that shows how to use the JAXB binding.  
     101Use this with any of the test data supplied with the cansas-1d-standard 
     102directory (above). By default, it shows the two samples in the 
     103*1998spheres.xml* example file. 
     104(http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/1998spheres.xml) 
     105 
     106.. note:: The reader will have to get the directory paths  
     107        right until this documentation improves. 
     108 
     109.. literalinclude:: ../src/Example_canSAS_Reader.java 
     110   :language: java 
     111   :linenos: 
     112 
     113.. index:: I(Q) 
     114 
     115example: how to retrieve :math:`I(Q)` 
     116============================================ 
     117 
     118This is a slightly longer example. 
     119Look near line 75 for this code: 
     120 
     121.. code-block:: java 
     122         
     123        Qsas[i] = sdt.getIdata().get(i).getQ().getValue(); 
     124 
     125to see the operations that unwind the data into usable *double[]* 
     126vectors. Pretty straightforward although there is lots of 
     127interesting, yet unnecessary, diagnostic output.  Here is a table 
     128that describes the items in the line just shown: 
     129 
     130==============  ================================================ 
     131java item       description 
     132==============  ================================================ 
     133*sdt*           *SASdataType* object 
     134*getIdata()*    amongst the */SASdata/Idata* tuples ... 
     135*get(i)*        ... pick the *Idata* tuple from row *i*. 
     136*getQ()*        Just the */SASdata/Idata/Q* 
     137*getValue()*    and specifically the value, not the unit 
     138==============  ================================================ 
     139 
     140.. index:: Java file; GetSASdata.java 
     141 
     142*GetSASdata.java* 
     143------------------- 
     144 
     145Since the source code is rather lengthy, download it from: 
     146http://svn.smallangles.net/svn/canSAS/1dwg/trunk/doc/src/GetSASdata.java 
     147 
     148.. 
     149        .. literalinclude:: ../src/GetSASdata.java 
     150           :language: java 
     151           :linenos: 
     152 
     153.. index:: Java file; java-test.java 
     154 
     155.. _java-test.xml: 
     156 
     157*java-test.xml* 
     158------------------ 
     159 
     160*java-test.xml* is an example cansas1d/1.1 XML data file 
     161(derived from the standard test file for the *lake*  
     162desmearing code). 
     163 
     164.. literalinclude:: ../src/java-test.xml 
     165   :language: xml 
     166   :linenos: 
     167 
     168 
     169.. index:: ! JAXB 
     170 
     171JAXB: Questions and Answers 
     172============================================ 
     173 
     174[Q]: What is *JAXB*? 
     175        [A]: Java Architecture for XML Binding 
     176        (http://java.sun.com/developer/technicalArticles/WebServices/jaxb) 
     177 
     178[Q]: Wow! : Is it available for other languages? 
     179        [A]: Ask Google. JAXB is for Java.  
     180        (http://java.sun.com/developer/technicalArticles/WebServices/jaxb) 
     181         
     182        For example: http://www.devx.com/ibm/Article/20261 
     183 
     184.. index:: I(Q) 
     185 
     186[Q]: How do I pull out the :math:`I(Q)` data? 
     187        [A]: See Java code fragment above that gets data for desmearing.  (:ref:`java-test.xml`) 
     188 
     189[Q]: Has JAXB been useful? 
     190        [A]: **Very useful.** 
     191        Since an XML Schema was defined, JAXB was  
     192        very useful to create a Java binding  
     193        automatically.  Then, *javadoc* was able to 
     194        auto-generate the basic documentation as HTML and  
     195        *pdfdoclet* was able to auto-generate the  
     196        documentation in a PDF file. 
  • 1dwg/trunk/doc/src/java-test.xml

    r233 r252  
    1313    xmlns="cansas1d/1.1" 
    1414    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    15     xsi:schemaLocation="cansas1d/1.0 http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd" 
     15    xsi:schemaLocation="cansas1d/1.1 http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd" 
    1616    > 
    1717    <SASentry> 
Note: See TracChangeset for help on using the changeset viewer.