Changeset 320


Ignore:
Timestamp:
Mar 29, 2013 4:57:37 PM (6 years ago)
Author:
prjemian
Message:

refs #23: revised documentation for java binding, other minor

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

Legend:

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

    r284 r320  
    4343 
    4444:date: 
    45         2009-09-02 
     45        2013-03-29 
    4646 
    4747:version: 
    48         1.11 (**requires** latest XMLutils XOP -- see below) 
     48        1.12 (**requires** latest XMLutils XOP -- see below) 
    4949 
    5050:purpose: 
  • 1dwg/trunk/doc/source/binding-java-jaxb.rst

    r315 r320  
    99================ 
    1010 
    11 .. note:: FIX THIS into a how-to use the JAR file to read canSAS data files 
    12  
    13 A Java binding for the cansas1d:1.1 standard has been auto-created using the JAXB tools 
    14 from Sun (see below for more on JAXB) using the *cansas1d.xsd* :index:`XML Schema`. 
    15 Resources (JAR files and documentation) for the Java binding may be found in 
    16 the canSAS subversion repository: http://www.cansas.org/svn/1dwg/tags/v1.0/java 
    17  
    18 Subversion repository 
    19         http://www.cansas.org/svn/1dwg/tags/v1.0/java 
    20          
    21         canSAS subversion repository tagged release directory for the Java binding. 
    22         Use resources from this directory in your development projects. 
    23  
    24 *cansas1d-1.0.jar* 
    25         http://www.cansas.org/svn/1dwg/tags/v1.0/java/cansas1d-1.0.jar 
    26          
    27         JAR file to add to your CLASSPATH in order to use this binding. 
    28  
    29 *cansas1d-1.0-javadoc.jar* 
    30         http://www.cansas.org/svn/1dwg/tags/v1.0/java/cansas1d-1.0-javadoc.jar 
    31          
    32         Use this JAR file if you want to add the  
    33         javadoc documentation as tooltips to your editor, such as eclipse.  
    34         (auto-generated from the project source code using maven2) 
    35         Note that this file is compatible with any ZIP program and can be unzipped 
    36         to provide a directory with all the documentation as a set of HTML pages. 
    37         Start with the *index.html* page. 
    38  
    39 *cansas1d-1.0-sources.jar* 
    40         http://www.cansas.org/svn/1dwg/tags/v1.0/java/cansas1d-1.0-sources.jar 
    41          
    42         JAR file of the source code.    
    43         (auto-generated from the project source code using maven2) 
    44         Note that this is *just* 
    45         the source code tree and not the full project development tree 
    46         for the Java (JAXB) API. 
    47  
    48 *cansas1d-1.0.pdf* 
    49         http://www.cansas.org/svn/1dwg/tags/v1.0/java/cansas1d-1.0.pdf 
    50  
    51         PDF file of the javadoc source code documentation. 
    52         (auto-generated from the project source code using pdfdoclet) 
    53  
    54 source code (for developers) 
    55         http://www.cansas.org/trac/browser/1dwg/trunk/java/maven/eclipse 
    56          
    57         canSAS Development project subversion repository for the Java binding.   
    58         Only use this if you want to participate as a code developer of this binding. 
    59  
    60  
    61 *Example_canSAS_Reader.java*: example usage in JAVA 
    62 ======================================================= 
    63  
    64 An example (*Example_canSAS_Reader.java*) has been constructed 
    65 to show how to read a cansas1d:1.1 XML file using the Java API.  
    66  
    67 http://www.cansas.org/trac/browser/1dwg/trunk/java/maven/eclipse/src/main/java/org/scatteringsw/reader/Example_canSAS_Reader.java 
    68  
    69 In short, these are the important two lines: 
     11A Java binding for the cansas1d:1.1 standard has been auto-created  
     12using the JAXB tools from Oracle (formerly Sun, see below for more  
     13on JAXB) using the *cansas1d.xsd* :index:`XML Schema`.  See the  
     14:ref:`binding.java.download` section below. 
     15 
     16 
     17Using the Java Binding 
     18====================== 
     19 
     20The basics of the binding are these java statements: 
    7021 
    7122.. code-block:: java 
    7223 
    73         CanSas1dType reader = new CanSas1dType(); 
    74  
    75 and 
     24                // associate a JAXB context with the canSAS namespace URI 
     25                jc = JAXBContext.newInstance("org.cansas.cansas1d");  
     26                Unmarshaller unmarshaller = jc.createUnmarshaller(); 
     27 
     28                // open an XML file from local storage 
     29                InputStream in = new FileInputStream("a/data/file.xml); 
     30 
     31                // load the XML file into a Java data structure 
     32                xmlJavaData = (JAXBElement<SASrootType>) unmarshaller.unmarshal(in); 
     33                 
     34                // get the SASroot object 
     35                SASrootType sasroot = xmlJavaData.getValue() 
     36 
     37With a `SASroot` object, one can iterate over the `SASentry` groups  
     38and, for instance, print the `Title` string: 
    7639 
    7740.. code-block:: java 
    7841 
    79         SASrootType sasRoot = reader.open(xmlFile); 
    80  
    81 where *String xmlFile;* is the name of the XML file to be read.  
    82 You will also need these imports: 
    83  
    84 .. code-block:: java 
    85         :linenos: 
    86          
    87         import javax.xml.bind.JAXBException; 
    88          
    89         import net.smallangles.cansas1d.CanSas1dType; 
    90         import net.smallangles.cansas1d.SASdataType; 
    91         import net.smallangles.cansas1d.SASentryType; 
    92         import net.smallangles.cansas1d.SASrootType; 
    93         import net.smallangles.cansas1d.SASentryType.Run; 
    94  
    95 Also, since *CanSas1dType.open(xmlFile)* can throw a 
    96 *JAXBException*, you should use a *try{} catch {}* 
    97 clause. See the source code for the example. 
    98  
    99 .. index::  
    100         Java file; Example_canSAS_Reader.java 
    101         XML file; 1998spheres.xml 
    102  
    103 Here is a Java class that shows how to use the JAXB binding.  
    104 Use this with any of the test data supplied with the cansas-1d-standard 
    105 directory (above). By default, it shows the two samples in the 
    106 *1998spheres.xml* example file. 
    107 (http://www.cansas.org/trac/browser/1dwg/trunk/1998spheres.xml) 
    108  
    109 .. note:: The reader will have to get the directory paths  
    110         right until this documentation improves. 
    111  
    112 .. literalinclude:: examples/Example_canSAS_Reader.java 
    113    :language: java 
    114    :linenos: 
     42        for ( SASentryType entry : sasroot.getSASentry() ) { 
     43                System.out.printf("SASentry Title:  %s\n", entry.getTitle()); 
     44        } 
     45 
     46Full example 
     47---------------------- 
     48 
     49An example that uses the binding is provided in the java support  
     50and is available for direct  
     51:download:`download <../../java/ant-eclipse/src/org/cansas/cansas1d/demo/Reader.java>` 
     52or may be viewed using a web browser: 
     53http://www.cansas.org/trac/browser/1dwg/trunk/java/ant-eclipse/src/org/cansas/cansas1d/demo/Reader.java 
     54 
     55Output from `Reader.java` is:: 
     56 
     57        class: org.cansas.cansas1d.demo.Reader 
     58        SVN ID: $Id$ 
     59         
     60         
     61        File: ./resources/cansas1d/cs_collagen.xml 
     62        SASentry elements: 1 
     63        SASentry 
     64        Title:  dry chick collagen, d = 673 A, 6531 eV, X6B 
     65        #Runs:  1 
     66        Run@name:        
     67        Run:    Sep 19 1994     01:41:02 am 
     68        #SASdata:       1 
     69        SASdata@name:    
     70        #points:        125 
     71         
     72        the end. 
     73         
     74         
     75        File: ./resources/cansas1d/1998spheres.xml 
     76        SASentry elements: 2 
     77        SASentry 
     78        Title:  255 nm PS spheres 
     79        #Runs:  1 
     80        Run@name:        
     81        Run:    scan2.dat, scan 5 
     82        #SASdata:       1 
     83        SASdata@name:    
     84        #points:        1824 
     85         
     86        SASentry 
     87        Title:  460 nm PS spheres 
     88        #Runs:  1 
     89        Run@name:        
     90        Run:    scan1.dat, scan 67 
     91        #SASdata:       1 
     92        SASdata@name:    
     93        #points:        3689 
     94         
     95        the end. 
     96         
     97         
     98        File: cannot_find_this.xml 
     99        File not found: cannot_find_this.xml 
     100 
     101 
    115102 
    116103.. index:: I(Q) 
     104 
     105.. _binding.java.howto.I: 
    117106 
    118107example: how to retrieve :math:`I(Q)` 
     
    124113.. code-block:: java 
    125114         
    126         Qsas[i] = sdt.getIdata().get(i).getQ().getValue(); 
    127         Isas[i] = sdt.getIdata().get(i).getI().getValue(); 
     115        SASdataType sasdata = sasroot.getSASentry().getSASdata() 
     116        // ... 
     117        Qsas[i] = sasdata.getIdata().get(i).getQ().getValue(); 
     118        Isas[i] = sasdata.getIdata().get(i).getI().getValue(); 
    128119 
    129120to see the operations that unwind the data into usable *double[]* 
     
    135126java item       description 
    136127==============  ================================================ 
    137 *sdt*           *SASdataType* object 
     128*sasdata*       *SASdataType* object 
    138129*getIdata()*    amongst the */SASdata/Idata* tuples ... 
    139130*get(i)*        ... pick the *Idata* tuple from row *i*. 
     
    142133==============  ================================================ 
    143134 
    144 .. index:: Java file; GetSASdata.java 
    145  
    146 *GetSASdata.java* 
    147 ------------------- 
    148  
    149 Since the source code is rather lengthy, download it from: 
    150 http://www.cansas.org/svn/1dwg/trunk/doc/src/GetSASdata.java 
    151  
    152 .. 
    153         .. literalinclude:: examples/GetSASdata.java 
    154            :language: java 
    155            :linenos: 
    156  
    157 .. index:: Java file; java-test.java 
    158  
    159 .. _java-test.xml: 
    160  
    161 *java-test.xml* 
    162 ------------------ 
    163  
    164 *java-test.xml* is an example cansas1d:1.1 XML data file 
    165 (derived from the standard test file for the *lake*  
    166 desmearing code). 
    167  
    168 .. literalinclude:: examples/java-test.xml 
    169    :language: xml 
    170    :linenos: 
     135 
     136 
     137.. _binding.java.download: 
     138 
     139Downloading 
     140=========== 
     141 
     142Resources  
     143(JAR files and documentation) for the Java binding may be found  
     144in the canSAS subversion :ref:`repository`. 
     145 
     146*cansas1d-#.#.jar* 
     147        JAR file to add to your CLASSPATH in order to use this binding. 
     148        Adheres to canSAS 1D standard version #.#. 
     149 
     150*cansas1d-#.#-javadoc.jar* 
     151        http://www.cansas.org/svn/1dwg/tags/v#.#/java/cansas1d-#.#-javadoc.jar 
     152         
     153        Use this JAR file if you want to add the source code documentation 
     154        as tooltips to your editor, such as eclipse.  
     155        Note that this file is compatible with any ZIP program and can be unzipped 
     156        to provide a directory with all the documentation as a set of HTML pages. 
     157        Start with the *index.html* page. 
     158        Adheres to canSAS 1D standard version #.#. 
     159 
     160*cansas1d-#.#-sources.jar*       
     161        JAR file of the source code.    
     162        Note that this is *just* the source code tree and not  
     163        the full project development tree for the Java (JAXB) API. 
     164        Adheres to canSAS 1D standard version #.#. 
     165 
     166source code (for developers) 
     167        http://www.cansas.org/trac/browser/1dwg/trunk/java/ant-eclipse 
     168         
     169        canSAS Development project subversion repository for the Java binding.   
     170        Only use this if you want to participate as a code developer of this binding. 
    171171 
    172172 
     
    189189 
    190190:Q: How do I pull out the :math:`I(Q)` data? 
    191 :A: See Java code fragment above that gets data for desmearing.  (:ref:`java-test.xml`) 
     191:A: See Java code fragment :ref:`above <binding.java.howto.I>` 
    192192 
    193193:Q: Has JAXB been useful? 
Note: See TracChangeset for help on using the changeset viewer.