001/*
002 *   GeomReader  -- Interface for classes that read and write geometry files.
003 *
004 *   Copyright (C) 2000-2016, by Joseph A. Huwaldt
005 *   All rights reserved.
006 *   
007 *   This library is free software; you can redistribute it and/or
008 *   modify it under the terms of the GNU Lesser General Public
009 *   License as published by the Free Software Foundation; either
010 *   version 2 of the License, or (at your option) any later version.
011 *   
012 *   This library is distributed in the hope that it will be useful,
013 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
014 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015 *   Library General Public License for more details.
016 *
017 *  You should have received a copy of the GNU Lesser General Public License
018 *  along with this program; if not, write to the Free Software
019 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
020 *  Or visit:  http://www.gnu.org/licenses/lgpl.html
021 */
022package geomss.geom.reader;
023
024import geomss.geom.GeometryList;
025import java.io.File;
026import java.io.IOException;
027import java.util.List;
028import javax.measure.quantity.Length;
029import javax.measure.unit.Unit;
030
031/**
032 * Interface for classes that read and write geometry files of various formats. Sub-classes
033 * actually do the translation to and from the data file's format.
034 * 
035 * <p> Modified by: Joseph A. Huwaldt </p>
036 * 
037 * @author Joseph A. Huwaldt, Date: April 14, 2000
038 * @version September 9, 2016
039 */
040public interface GeomReader extends Comparable {
041
042    /**
043     * Constant indicating that a reader certainly <I>can not</I> read a specified file.
044     */
045    public static final int NO = 0;
046
047    /**
048     * Constant indicating that a reader certainly <I>can</I> read a specified file.
049     */
050    public static final int YES = 1;
051
052    /**
053     * Constant indicating that a reader <I>might</I> be able to read a specified file,
054     * but can't determine for sure.
055     */
056    public static final int MAYBE = -1;
057
058    /**
059     * Reads in a geometry file from the supplied input file and returns a
060     * {@link GeometryList} object that contains the geometry from the file.
061     * <p>
062     * WARNING: If the file being read in is not unit aware, then you must set the units
063     * to be used by calling "setFileUnits()" before calling this method!
064     * </p>
065     *
066     * @param inputFile The input file containing the geometry to be read in. May not 
067     *                  be null.
068     * @return A {@link GeometryList} object containing the geometry read in from the
069     *         file.
070     * @throws IOException If there is a problem reading the specified file.
071     * @see #setFileUnits(javax.measure.unit.Unit)
072     */
073    public GeometryList read(File inputFile) throws IOException;
074
075    /**
076     * Writes out a geometry file for the geometry contained in the supplied
077     * {@link GeometryList} object.
078     * <p>
079     * WARNING: If the format being written is not unit aware,
080     * then the values are written out in whatever their current units are!
081     * Make sure to convert to the desired units for the file before calling this method.
082     * </p>
083     *
084     * @param outputFile The output File to which the geometry is to be written. May not
085     *                   be null.
086     * @param geometry   The {@link GeometryList} object containing the geometry to be
087     *                   written out. May not be null.
088     * @throws IOException If there is a problem writing to the specified file.
089     */
090    public void write(File outputFile, GeometryList geometry) throws IOException;
091
092    /**
093     * Method that determines if this reader can read geometry from the specified input
094     * file.
095     *
096     * @param inputFile The input file containing the geometry to be read in.
097     * @return GeomReader.NO if the file format is not recognized by this reader.
098     *         GeomReader.YES if the file format is definitely recognized by this reader.
099     *         GeomReader.MAYBE if the file format might be readable by this reader, but
100     *         that can't easily be determined without actually reading the file.
101     * @throws java.io.IOException If there is a problem reading from the specified
102     * file.
103     */
104    public int canReadData(File inputFile) throws IOException;
105
106    /**
107     * Returns true if this class can write at least some data in the format supported by
108     * this class. Returns false if it can not.
109     *
110     * @return true if this class can write at least some data in the format supported by
111     *         this class.
112     */
113    public boolean canWriteData();
114
115    /**
116     * Returns the preferred file extension (not including the ".") for files of this
117     * GeomReader's type.
118     *
119     * @return The preferred file extension for files of this readers type.
120     */
121    public String getExtension();
122
123    /**
124     * Sets the units used for the geometry as stored in a non-unit aware geometry file
125     * being read in. The geometry is returned in these units for file types which are not
126     * unit aware. If the file format specifies units, the input from this method will be
127     * ignored. If this method is not called before reading a non-unit aware geometry
128     * file, then the units of the returned geometry will be the system default units.
129     * When writing out geometry, this is ignored.
130     *
131     * @param units The units used for the geometry in the file being read in. If null is
132     *              passed, the units will default to the default system units.
133     * @see #isUnitAware()
134     */
135    public void setFileUnits(Unit<Length> units);
136
137    /**
138     * Returns <code>true</code> if this reader is unit aware (the format it reads from or
139     * writes to stores the units being used) and returns <code>false</code> otherwise.
140     *
141     * @return true if this reader (and its format) is unit aware.
142     * @see #setFileUnits(javax.measure.unit.Unit) 
143     */
144    public boolean isUnitAware();
145
146    /**
147     * Return a list of any warning messages that the reader/writer may have issued.
148     *
149     * @return A list of any warning messages that the reader/writer may have issued.
150     */
151    public List<String> getWarnings();
152
153}