Ignore:
Timestamp:
2013-03-22T22:18:26+01:00 (13 years ago)
Author:
zverik
Message:

ImageryID refactoring and javadocs

File:
1 edited

Legend:

Unmodified
Added
Removed

  • applications/editors/josm/plugins/imagery_offset_db/src/iodb/IODBReader.java

    r29376 r29384  
    1818
    1919/**
    20  * Parses the message from server. It expects XML in UTF-8 with several <offset> elements.
     20 * Parses the server response. It expects XML in UTF-8 with several <offset>
     21 * and <calibration> elements.
    2122 *
    22  * @author zverik
     23 * @author Zverik
     24 * @license WTFPL
    2325 */
    2426public class IODBReader {
    … …  
    2628    private InputSource source;
    2729   
     30    /**
     31     * Initializes the parser. This constructor creates an input source on the input
     32     * stream, so it may throw an exception (though it's highly improbable).
     33     * @param source An input stream with XML.
     34     * @throws IOException Thrown when something's wrong with the stream.
     35     */
     36    public IODBReader( InputStream source ) throws IOException {
     37        this.source = new InputSource(UTFInputStreamReader.create(source, "UTF-8"));
     38        this.offsets = new ArrayList<ImageryOffsetBase>();
     39    }
     40
     41    /**
     42     * Parses the XML input stream. Creates {@link Parser} to do it.
     43     * @return The list of offsets.
     44     * @throws SAXException Thrown when the XML is malformed.
     45     * @throws IOException Thrown when the input stream fails.
     46     */
     47    public List<ImageryOffsetBase> parse() throws SAXException, IOException {
     48        Parser parser = new Parser();
     49        try {
     50            SAXParserFactory factory = SAXParserFactory.newInstance();
     51            factory.newSAXParser().parse(source, parser);
     52            return offsets;
     53        } catch( ParserConfigurationException e ) {
     54            throw new SAXException(e);
     55        }
     56    }
     57
     58    /**
     59     * The SAX handler for XML from the imagery offset server.
     60     * Calls {@link IOFields#constructObject()} for every complete object
     61     * and appends the result to offsets array.
     62     */
    2863    private class Parser extends DefaultHandler {
    2964        private StringBuffer accumulator = new StringBuffer();
    … …  
    3368        private SimpleDateFormat dateParser = new SimpleDateFormat("yyyy-MM-dd");
    3469
     70        /**
     71         * Initialize all fields.
     72         */
    3573        @Override
    3674        public void startDocument() throws SAXException {
    … …  
    4078        }
    4179
     80        /**
     81         * Parses latitude and longitude from tag attributes.
     82         * It expects to find them in "lat" and "lon" attributes
     83         * as decimal degrees. Note that it does not check whether
     84         * the resulting object is valid: it may not be, especially
     85         * for locations near the Poles and 180th meridian.
     86         */
    4287        private LatLon parseLatLon(Attributes atts) {
    4388            return new LatLon(
    … …  
    111156                        offsets.add(fields.constructObject());
    112157                    } catch( IllegalArgumentException ex ) {
     158                        // On one hand, we don't care, but this situation is one
     159                        // of those "it can never happen" cases.
    113160                        System.err.println(ex.getMessage());
    114161                    }
    … …  
    119166    }
    120167   
    121 
    122     public IODBReader( InputStream source ) throws IOException {
    123         this.source = new InputSource(UTFInputStreamReader.create(source, "UTF-8"));
    124         this.offsets = new ArrayList<ImageryOffsetBase>();
    125     }
    126    
    127     public List<ImageryOffsetBase> parse() throws SAXException, IOException {
    128         Parser parser = new Parser();
    129         try {
    130             SAXParserFactory factory = SAXParserFactory.newInstance();
    131             factory.newSAXParser().parse(source, parser);
    132             return offsets;
    133         } catch (ParserConfigurationException e) {
    134             e.printStackTrace();
    135             throw new SAXException(e);
    136         }
    137     }
    138    
     168    /**
     169     * An accumulator for parsed fields. When there's enough data, it can construct
     170     * an offset object. All fields are public to deliver us from tons of getters
     171     * and setters.
     172     */
    139173    private class IOFields {
    140174        public int id;
    … …  
    151185        public List<LatLon> geometry;
    152186
     187        /**
     188         * A constructor just calls {@link #clear()}.
     189         */
    153190        public IOFields() {
    154191            clear();
    155192        }
    156193       
     194        /**
     195         * Clear all fields to <tt>null</tt> and <tt>-1</tt>.
     196         */
    157197        public void clear() {
    158198            id = -1;
    … …  
    171211        }
    172212
     213        /**
     214         * Creates an offset object from the fields. Also validates them, but not vigorously.
     215         * @return A new offset object.
     216         */
    173217        public ImageryOffsetBase constructObject() {
    174218            if( author == null || description == null || position == null || date == null )
Note: See TracChangeset for help on using the changeset viewer.