The PIRL Java Packages are free software; you can redistribute them and/or modify them under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
The PIRL Java Packages are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.
Comments, corrections, contributions, and queries can be sent to the
author at the address below. To be put on an email list for update
notifications send your request to the email address below along with a
brief description of how you use the software.
| Bradford Castalia | Castalia@Arizona.edu |
| Senior Systems Analyst | |
| University of Arizona | Tucson, Arizona |
| Department of Planetary Sciences | Planetary Image Research Laboratory |
"Build an image in your mind, fit yourself into it."
' \
-bottom 'Copyright (C) \
2003-2009 Bradford Castalia, University of Arizona' \
-sourcepath ../.. \
-classpath $(JPATH) \
$(PACKAGE_PATHS) $(SUBPACKAGES)
cp PIRL_icon.gif Copyright.html $(PIRL_DOCS_DIR)
# Application wrappers installation:
install:
@echo
@echo "=== Installing application wrappers in $(INSTALL_DIR)"
cp -f $(addprefix ../,$(APPLICATIONS)) $(INSTALL_DIR)
# Distribution files:
# Source code tarball
tarball: $(PIRL_TARBALL)
$(PIRL_TARBALL):
@echo
@echo "=== $@ ==="
@echo
-rm -f $@
@if [ ! -d staging_area/PIRL ]; then \
echo ; \
echo "--- Assembling the package files" ; \
mkdir -p staging_area/PIRL ; \
Release -dir staging_area/PIRL -no_make Build $(PACKAGES) ; \
fi
@echo
mv staging_area/PIRL staging_area/$(PIRL_VERSION)
cd staging_area; gtar czf ../$@ $(PIRL_VERSION)
mv staging_area/$(PIRL_VERSION) staging_area/PIRL
# Javadoc tarball
javadoc.tarball: $(PIRL_JAVADOC)
$(PIRL_JAVADOC):
@echo
@echo "=== $@ ==="
@echo
-rm -f $@
@if [ ! -d staging_area/PIRL/docs ]; then \
echo ; \
echo "--- Assembling the package files" ; \
mkdir -p staging_area/PIRL ; \
Release -dir staging_area/PIRL -no_make Build $(PACKAGES) ; \
fi
@echo
$(MAKE) -C staging_area/PIRL/Build docs
mv staging_area/PIRL staging_area/$(PIRL_VERSION)
cd staging_area; gtar czf ../$@ $(PIRL_VERSION)/docs
mv staging_area/$(PIRL_VERSION) staging_area/PIRL
# Jar
jar: $(PIRL_JAR)
$(PIRL_JAR):
@echo
@echo "=== $@ ==="
@echo
-rm -f $@
@echo "--- Preparing the jar files"
@if [ ! -d staging_area/PIRL/Build ]; then \
echo ; \
echo "--- Assembling the package files" ; \
mkdir -p staging_area/PIRL ; \
Release -dir staging_area/PIRL -no_make Build $(PACKAGES) ; \
fi
@echo
$(MAKE) -C staging_area/PIRL/Build
@echo
cd staging_area/PIRL/Build; cp -f $(BOILERPLATE) VERSION ..
@echo
@echo "--- Removing extraneous files"
mv staging_area/PIRL/Build staging_area
rm -rf staging_area/PIRL/docs
find staging_area/PIRL/Conductor \
-type d -name '*.*' \
-exec rm -rf {} \; -prune
find staging_area/PIRL \
-type d -name tests \
-exec rm -rf {} \; -prune
find staging_area/PIRL \
\( -name '*.java' -o -name Makefile -o -name '*.html' \) \
-exec rm {} \;
@echo
@echo "--- Preparing the MANIFEST"
sed -e s/VERSION/$(VERSION)/ \
-e '/MAIN/ d' \
PIRL-MANIFEST.template > MANIFEST
@echo
@echo "--- Filling the jar"
cd staging_area; jar cmf ../MANIFEST ../$(PIRL_JAR) PIRL
-rm -f MANIFEST
dist: .BEGIN tarball javadoc.tarball jar .END
distribute: dist
@echo
@echo "=== Distribution ==="
@echo
@echo "--- Archiving the tarballs and jar files to the archive directory."
mkdir -p ../archive
cp -f $(PIRL_TARBALL) $(PIRL_JAVADOC) $(PIRL_JAR) ../archive
@echo
@echo "--- Moving the distribution files to the $(DIST_DIR) directory."
mkdir -p $(DIST_DIR)
mv -f \
$(PIRL_TARBALL) \
$(PIRL_JAVADOC) \
$(PIRL_JAR) \
$(DIST_DIR)
rm -f \
$(DIST_DIR)/$(PIRL_TARBALL:-$(VERSION).tar.gz=.tar.gz) \
$(DIST_DIR)/$(PIRL_JAVADOC:-$(VERSION).tar.gz=.tar.gz) \
$(DIST_DIR)/$(PIRL_JAR:-$(VERSION).jar=.jar)
ln -s $(PIRL_TARBALL) $(DIST_DIR)/$(PIRL_TARBALL:-$(VERSION).tar.gz=.tar.gz)
ln -s $(PIRL_JAVADOC) $(DIST_DIR)/$(PIRL_JAVADOC:-$(VERSION).tar.gz=.tar.gz)
ln -s $(PIRL_JAR) $(DIST_DIR)/$(PIRL_JAR:-$(VERSION).jar=.jar)
cd staging_area/Build; cp -f $(BOILERPLATE) $(DIST_DIR)
@echo
@echo "--- Copying the application files to the $(DIST_DIR)/Apps directory."
rm -rf $(DIST_DIR)/Apps
mkdir -p $(DIST_DIR)/Apps
cp -f $(addprefix staging_area/PIRL/,$(APPLICATIONS)) $(DIST_DIR)/Apps
@echo
@echo "--- Copying the configuration files to the $(DIST_DIR)/Configs directory."
rm -rf $(DIST_DIR)/Configs
mkdir -p $(DIST_DIR)/Configs
cp -f $(addprefix staging_area/PIRL/,$(CONFIGURATIONS)) $(DIST_DIR)/Configs
@echo
@echo "--- Cleanup"
rm -rf staging_area
rm -rf staging_area
rm -rf staging_area
# Cleaning:
clean: TARGET = clean
clean: packages
distclean: dist_clean
dist_clean:
rm -f $(PIRL_TARBALL) $(PIRL_TARBALL:-$(VERSION).tar.gz=.tar.gz)
rm -f $(PIRL_JAVADOC) $(PIRL_JAVADOC:-$(VERSION).tar.gz=.tar.gz)
rm -f $(PIRL_JAR) $(PIRL_JAR:-$(VERSION).jar=.jar)
rm -rf MANIFEST staging_area
# Release:
release:
@echo
@echo "*** $(TITLE) release $(VERSION)"
@echo
Release -d .. -no_make -no_strip $(PACKAGES)
@echo
$(MAKE) packages docs
@echo
@echo "*** $(TITLE) release $(VERSION) completed."
# Reporting:
.BEGIN:
@echo
@echo "*** $(TITLE) $(CVS_ID) ***"
@date
@echo
.END:
@echo
@echo "*** $(TITLE) Completed ***"
@date
@echo
.PHONY: .BEGIN \
all packages $(PACKAGES) clean docs \
tarball javadoc.tarball jar \
dist distribute distclean dist_clean wipe release \
.END
pirl-2.3.8/PIRL/Build/VERSION 0000644 0001750 0001750 00000000146 12052275051 015221 0 ustar mathieu mathieu PIRL Java Packages release version:
2.3.8
CVS ID: VERSION,v 1.107 2012/11/19 00:15:37 castalia Exp
pirl-2.3.8/PIRL/Image_Tools/ 0000755 0001750 0001750 00000000000 12052546526 015323 5 ustar mathieu mathieu pirl-2.3.8/PIRL/Image_Tools/JPEG2000_Info.java 0000644 0001750 0001750 00000110566 11742733714 020203 0 ustar mathieu mathieu /* JPEG2000_Info
HiRISE CVS ID: JPEG2000_Info.java,v 1.25 2012/04/16 06:10:20 castalia Exp
Copyright (C) 2006-2012 Arizona Board of Regents on behalf of the
Planetary Image Research Laboratory, Lunar and Planetary Laboratory at
the University of Arizona.
This file is part of the PIRL Java Packages.
The PIRL Java Packages are free software; you can redistribute them
and/or modify them under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
The PIRL Java Packages are distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see This class is intended to be the base class for JP2_Info and JPEG2000_Codestream_Info Parameter sets. The JPEG2000_Info methods know how to manage the assigned ImageInputStream to obtain data values and keep track of the stream position, but it expects its subclasses to know how to use the data values to generate the appropriate Parameters.
@author Bradford Castalia UA/PIRL @version 1.25 @see PIRL.Image_Tools.JP2_Info @see PIRL.Image_Tools.JPEG2000_Codestream_Info */ public class JPEG2000_Info extends Parameter { /** Class identification name with source code version and date. */ public static final String ID = "PIRL.Image_Tools.JPEG2000_Info (1.25 2012/04/16 06:10:20)"; /** Parameter name for specifying the position of data in the Source file (byte offset from the beginning of the file). */ public static final String DATA_POSITION_PARAMETER = "^Data_Position"; /** Parameter name for specifying a data block offset in an enclosing object.
For JP2 boxes, the offset is relative to the byte immediately following the box header's length, type and extended length (if present) fields.
For codestream segements, the offset is relative to the byte immediately following the segment marker and length fields. */ public static final String DATA_OFFSET_PARAMETER = "Data_Offset"; /** Parameter name for specifying the length (bytes) of a data block. */ public static final String DATA_LENGTH_PARAMETER = "Data_Length"; /** Parameter name for specifying the bit precision of a value. */ public static final String VALUE_BITS_PARAMETER = "Value_Bits"; /** Value of a bit precision Parameter value when the number of bits is variable. */ public static final int BITS_VARIABLE = 0; /** Generic parameter names used by both JP2_Info and JPEG20000_Codestream_Info */ public static final String LENGTH_PARAMETER = "Length", POSITION_PARAMETER = "^Position", TOTAL_COMPONENTS_PARAMETER = "Total_Components"; //! Warning message parameter name. public static final String WARNING_PARAMETER = "WARNING"; //! Name for an unrecognized box type or segment marker. public static final String UNKNOWN = "Unknown"; /** The ImageInputStream Source from which the JPEG2000 information is obtained.
@see #Source() */ protected ImageInputStream Image_Input_Stream = null; /** The current read position of the Source file.
@see #Stream_Position() */ protected long Stream_Position = -1; /** Default flag for skipping tile segments.
@see #Skip_Tiles(boolean) */ public static boolean Skip_Tiles_Default = true; /** Flag for skipping tile segments.
@see #Skip_Tiles(boolean) */ protected boolean Skip_Tiles = Skip_Tiles_Default; /** Default flag for using {@link #Data_Position_Parameters(Parameter, long) data position parameters} in preference to {@link #Data_Offset_Parameters(Parameter, long, long) data offset parameters}.
@see #Use_Data_Position(boolean) */ public static boolean Use_Data_Position_Default = true; /** Flag for using {@link #Data_Position_Parameters(Parameter, long) data position parameters} in preference to {@link #Data_Offset_Parameters(Parameter, long, long) data offset parameters}.
@see #Use_Data_Position(boolean)
*/
protected boolean
Use_Data_Position = Use_Data_Position_Default;
/** Default flag for throwing an IllegalStateException when the Source is
found to contain an invalid box or segment organization or contents.
@param file The File from which to obtain the JPEG2000_Info.
@throws IOException If there was a problem reading the file.
*/
public JPEG2000_Info
(
File file
)
throws IOException
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> JPEG2000_Info: " + file);
Classification (AGGREGATE);
Source (file);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< JPEG2000_Info");
}
/** Construct a JPEG2000_Info for an ImageInputStream.
@param image_input_stream The ImageInputStream from which to obtain
the JPEG2000_Info.
@throws IOException If there was a problem reading the file.
*/
public JPEG2000_Info
(
ImageInputStream image_input_stream
)
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> JPEG2000_Info: " + image_input_stream);
Classification (AGGREGATE);
Source (image_input_stream);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< JPEG2000_Info");
}
/** Construct a an empty JPEG2000_Info Object.
Use one of the Source methods to assign a source file.
*/
public JPEG2000_Info ()
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">-< JPEG2000_Info");
Classification (AGGREGATE);
}
/*==============================================================================
Accessors
*/
/** Assign a named file as the information source.
An attempt is made to form a URL from the source. If this succeeds an
HTTP_ImageInput_Stream is constructed from the URL and then delegated
to the {@link #Source(ImageInputStream)} method.
If a URL can not be formed from the source a File is constructed from
the source and then delegated to the {@link #Source(File)} method.
@param source The name of the source to use as the information source.
@return This JPEG2000_Info.
@throws UnknownHostException If the source is a URL but the
hostname is specifies can not be resolved.
@throws IllegalArgumentException If the source is a URL but does
not specify the http protocol or a source pathname.
@throws FileNotFoundException If the file could not be accessed for
any reason.
@throws ProtocolException If the source is a valid URL but an HTTP
{@link HTTP_ImageInputStream#Status() Status} protocol error was
returned by the server.
@throws IOException If there was a problem reading the source.
*/
public JPEG2000_Info Source
(
String source
)
throws IOException, UnknownHostException, IllegalArgumentException
{
if (source == null)
return this;
try
{
URL
url = new URL (source);
HTTP_ImageInputStream
image_input_stream = null;
try {image_input_stream = new HTTP_ImageInputStream (url);}
catch (IllegalArgumentException exception)
{
throw new IllegalArgumentException (ID + '\n'
+ "Inaccessble URL: " + url + '\n'
+ exception.getMessage ());
}
catch (UnknownHostException exception)
{
throw new UnknownHostException (ID + '\n'
+ "Inaccessble URL: " + url + '\n'
+ exception.getMessage ());
}
catch (FileNotFoundException exception)
{
throw new FileNotFoundException (ID + '\n'
+ "Inaccessble URL: " + url + '\n'
+ exception.getMessage ());
}
catch (ProtocolException exception)
{
throw new ProtocolException (ID + '\n'
+ "Inaccessble URL: " + url + '\n'
+ exception.getMessage ());
}
catch (IOException exception)
{
throw new IOException (ID + '\n'
+ "Inaccessble URL: " + url + '\n'
+ exception.getMessage ());
}
if (DEBUG != DEBUG_OFF)
image_input_stream.Logging (true);
Name (image_input_stream.Source_URL ().toString ());
return Source (image_input_stream);
}
catch (MalformedURLException exception) {}
return Source (new File (source));
}
/** Assign a File as the information source.
The name of this JPEG2000_Info is set to the canonical pathname of
the File.
An ImageInputStream is constructed from the file and then delegated
to the {@link #Source(ImageInputStream)} method.
@param file The File to use as the information source.
@return This JPEG2000_Info.
@throws FileNotFoundException If the file could not be accessed for
any reason.
@throws IOException If there was a problem reading the file.
*/
public JPEG2000_Info Source
(
File file
)
throws IOException
{
if (file == null)
return this;
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(">>> JPEG2000_Info.Source: File " + file.getCanonicalPath ());
if (! file.exists ())
throw new FileNotFoundException (ID + '\n'
+"Unable to obtain JP2 Info for Source file "
+ file.getCanonicalPath () + '\n'
+" because no file exists at that pathname.");
if (! file.isFile ())
throw new FileNotFoundException (ID + '\n'
+"Unable to obtain JP2 Info for Source file "
+ file.getCanonicalPath () + '\n'
+" because the file is not a regular file.");
if (! file.canRead ())
throw IO_Error
("Unable to obtain JP2 Info for Source file "
+ file.getCanonicalPath () + '\n'
+" because the file can not be read.");
ImageInputStream
image_input_stream = null;
try {image_input_stream = new FileImageInputStream (file);}
catch (IOException exception)
{
throw IO_Error
("Unable to obtain JP2 Info for Source file "
+ file.getCanonicalPath () + '\n'
+" because an ImageInputStream could not be created for it.",
exception);
}
Name (file.getCanonicalPath ());
Source (image_input_stream);
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
("<<< JPEG2000_Info.Source: File " + file.getCanonicalPath ());
return this;
}
/** Assign an ImageInputStream as the information source.
If the image_input_stream is null or identical to the currently
assigned ImageInputStream nothing is done.
If this JPEG2000_Info does not have a name it is set to
"ImageInputStream". All Parameters are removed. The current {@link
#Stream_Position() stream position} is determined.
@param image_input_stream The ImageInputStream to use as the
information source.
@return This JPEG2000_Info.
*/
public JPEG2000_Info Source
(
ImageInputStream image_input_stream
)
{
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(">>> JPEG2000_Info.Source: " + image_input_stream + '\n'
+" Current Image_Input_Stream: " + Image_Input_Stream);
if (image_input_stream != null &&
image_input_stream != Image_Input_Stream)
{
Image_Input_Stream = image_input_stream;
try {Stream_Position = Image_Input_Stream.getStreamPosition ();}
catch (IOException exception)
{
/* Shouldn't happen.
Just assume the beginning of the stream.
*/
Stream_Position = 0;
}
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(" Image_Input_Stream reset to " + Image_Input_Stream);
if (Name ().length () == 0)
Name ("ImageInputStream");
// Remove any and all current parameters.
Remove_All ();
}
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
("<<< JPEG2000_Info.Source");
return this;
}
/** Get the currently assigned ImageInputStream information source.
@return The currently assigned ImageInputStream. This will be null
if no source has been assigned.
*/
public ImageInputStream Source ()
{return Image_Input_Stream;}
/** Enable of disable skipping of tile segments.
When a codestream is being scanned for segment markers the tile-part
segments - which begin with a Start-Of_Tile (SOT) marker - may be
skipped. When there are many tiles in the codestream this will
significantly reduce the amount of time to scan the Source and the
number of Parameter groups generated.
@param enabled If true, tile-part segments will be skipped; otherwise
all tile-part segments will be examined and Parameter groups
assembled for each one.
@return This JPEG2000_Info.
*/
public JPEG2000_Info Skip_Tiles
(
boolean enabled
)
{Skip_Tiles = enabled; return this;}
/** Test if tile segments will be skipped.
@return true if tile segments will be skipped; false otherwise.
@see #Skip_Tiles(boolean)
*/
public boolean Skip_Tiles ()
{return Skip_Tiles;}
/** Enable or disable the use of Source data position parameters.
@param enabled If true, Source data position parameters are included
for all JP2 boxes and codestream segments, and used elsewhere.
Otherwise position parameters are not included and data offset
parameters are used elsewhere instead of position parameters.
@return This JPEG2000_Info.
*/
public JPEG2000_Info Use_Data_Position
(
boolean enabled
)
{Use_Data_Position = enabled; return this;}
/** Test if Source data position parameters will be used.
@return true if Source data position parameters will be used;
false otherwise.
@see #Use_Data_Position(boolean)
*/
public boolean Use_Data_Position ()
{return Use_Data_Position;}
/** Enable or disable throwing of IllegalStateException when an invalid
JP2 box or codestream segment structure or contents is encountered.
@param enabled If true an IllegalStateException will be thrown at
the point where the JP2 box or codestream segment structure is
determined to be invalid.
@return This JPEG2000_Info.
*/
public JPEG2000_Info Throw_Illegal_State
(
boolean enabled
)
{Throw_Illegal_State = enabled; return this;}
/** Test if IllegalStateException will be thrown when an invalid
JP2 box or codestream segment structure or contents is encountered.
@return true if IllegalStateException will be thrown when an invalid
JP2 box or codestream segment structure or contents is encountered;
false otherwise.
@see #Throw_Illegal_State(boolean)
*/
public boolean Throw_Illegal_State ()
{return Throw_Illegal_State;}
/*==============================================================================
Manipulators
*/
/** Get the next long data value from the Source.
The current {@link #Stream_Position() stream position} is updated.
@param description A String describing the value being obtained.
@return The next long data value from the Source.
@throws IOException If there was a problem reading from the Source.
*/
protected long Read_long
(
String description
)
throws IOException
{
try
{
long
datum = Image_Input_Stream.readLong ();
Stream_Position += 8;
return datum;
}
catch (IOException exception)
{throw IO_Error ("Unable to read " + description + " value.",
exception);}
}
/** Get the next int data value from the Source.
The current {@link #Stream_Position() stream position} is updated.
@param description A String describing the value being obtained.
@return The next int data value from the Source.
@throws IOException If there was a problem reading from the Source.
*/
protected int Read_int
(
String description
)
throws IOException
{
try
{
int
datum = Image_Input_Stream.readInt ();
Stream_Position += 4;
return datum;
}
catch (IOException exception)
{throw IO_Error ("Unable to read " + description + " value.",
exception);}
}
/** Get the next int data value from the Source as an unsigned integer.
The next {@link #Read_int(String) int value read from the Source} is
cast as a long value but without sign extension.
The current {@link #Stream_Position() stream position} is updated.
@param description A String describing the value being obtained.
@return A long value of the next int from the Source as an unsigned
integer value.
@throws IOException If there was a problem reading from the Source.
*/
protected long Read_Unsigned_int
(
String description
)
throws IOException
{return (long)Read_int (description) & 0xFFFFFFFF;}
/** Get the next short data value from the Source.
The current {@link #Stream_Position() stream position} is updated.
@param description A String describing the value being obtained.
@return An int value of the next short from the Source as a signed
integer value.
@throws IOException If there was a problem reading from the Source.
*/
protected int Read_short
(
String description
)
throws IOException
{
try
{
int
datum = Image_Input_Stream.readShort ();
Stream_Position += 2;
return datum;
}
catch (IOException exception)
{throw IO_Error ("Unable to read " + description + " value.",
exception);}
}
/** Get the next short data value from the Source as an unsigned integer.
The next {@link #Read_short(String) short value read from the Source} is
cast as an int value but without sign extension.
The current {@link #Stream_Position() stream position} is updated.
@param description A String describing the value being obtained.
@return An int value of the next short from the Source as an unsigned
integer value.
@throws IOException If there was a problem reading from the Source.
*/
protected int Read_Unsigned_short
(
String description
)
throws IOException
{return (int)Read_short (description) & 0xFFFF;}
/** Get the next byte data value from the Source.
The current {@link #Stream_Position() stream position} is updated.
@param description A String describing the value being obtained.
@return The next byte data value, as an int with sign extension from
the byte, from the Source.
@throws IOException If there was a problem reading from the Source.
*/
protected int Read_byte
(
String description
)
throws IOException
{
try
{
int
datum = Image_Input_Stream.readByte ();
++Stream_Position;
return datum;
}
catch (IOException exception)
{throw IO_Error ("Unable to read " + description + " value.",
exception);}
}
/** Get the next byte data value from the Source as an unsigned integer.
The current {@link #Stream_Position() stream position} is updated.
@param description A String describing the value being obtained.
@return An int value of the next byte from the Source as an unsigned
integer value.
@throws IOException If there was a problem reading from the Source.
*/
protected int Read_Unsigned_byte
(
String description
)
throws IOException
{return Read_byte (description) & 0xFF;}
/** Get a value of some bits precision from the Source.
If the number of bits is negative the most significant bit of the
value is treated as a sign bit (extended in the returned value) and
the actual precision of the value is abs (bits). The Source stream is
read starting at the current {@link #Stream_Position() stream
position}. Bytes are read from the stream starting with the most
significant byte of the value with the most significant bits right
justified in this first byte; the least significant bit is presumed
to be the least significant bit of the last byte read. The bytes read
are concatenated to form the value that is returned.
The current {@link #Stream_Position() stream position} is updated.
@param description A String describing the value being obtained.
@param bits The precision of the value is abs (bits). Negative
bits means the value is signed; i.e. the most significant bit is
the sign bit.
@return The value obtained as a long. Thus a maximum of 64 bits may
be obtained. As a special case, if bits is 0, 0 is returned.
@throws IOException If there was a problem reading the value bytes from
the Source stream.
@throws ArithmeticException If abs (bits) > 64.
*/
protected long Read_Value
(
String description,
int bits
)
throws IOException
{
long
value = 0;
if (bits != 0)
{
boolean
signed_value = false;
if (bits < 0)
{
bits = -bits;
if (bits < 64 && // 64-bit value does not need sign extension.
bits > 1) // 1-bit value is always unsigned.
signed_value = true;
}
if (bits > 64)
throw new ArithmeticException (ID + '\n'
+ "Unable to Read Value of " + bits + " bits.");
// Convert bits to bytes.
int
bytes = bits >> 3;
if ((bits % 8) != 0)
bytes++;
// Move the data bytes into the local variable.
while (bytes != 0)
{
value <<= 8;
value |= Read_Unsigned_byte (description + " byte " + bytes);
--bytes;
}
if (signed_value &&
(value & (1 << (bits - 1))) != 0)
{
// Sign extension.
long
mask = 0;
while (bits != 0)
{
mask <<= 1;
mask |= 1;
--bits;
}
value |= ~mask;
}
}
return value;
}
/** Get a String from the Source.
Starting at the current {@link #Stream_Position() stream position}
bytes are read up to, but not including, the end position. Each byte
read is concatenated as a character in the resultant String with
unprintable characters being expanded into printable escape
sequences. However, if the last character is null it is not
included in the String.
The current {@link #Stream_Position() stream position} is updated.
@param description A String describing the value being obtained.
@param end_position The end position in the Source after the
last byte to be read.
@return A String representing the bytes read from the source.
@throws IOException If there was a problem reading from the Source.
*/
protected String Read_String
(
String description,
long end_position
)
throws IOException
{
String
describe = description + " string";
char
character;
String_Buffer
string = new String_Buffer ();
while (Stream_Position < end_position)
{
if ((character = (char)Read_Unsigned_byte (describe)) == 0)
break;
if (Stream_Position < end_position ||
character != '\0')
string.append (character);
}
Stream_Position (end_position);
// Escape any non-printable characters.
string.special_to_escape ();
return string.toString ();
}
/** Set the stream position of the information Source.
If the specified position is the same as the current position of
the Source, nothing is done. Otherwise the current position of
the Source is changed to the specified position.
@param position The position, as a byte offset from the beginning
of the file, to which to reposition the image Source stream. This
value must be a non-negative value less than the size of the
Source file, otherwise an IOException will be thrown.
@throws IOException If the Source stream could not be repositioned. An
attempt will be made to reset the Source stream to return it to the
last marked position before the exception is thrown.
*/
protected void Stream_Position
(
long position
)
throws IOException
{
if (Stream_Position != position)
{
Exception
exception = null;
try
{
Image_Input_Stream.seek (position);
Stream_Position = position;
}
catch (IndexOutOfBoundsException except) {exception = except;}
catch (IOException except) {exception = except;}
if (exception != null)
{
String
message =
"Could not reposition the Source to position " + position + '.';
try {Image_Input_Stream.reset ();}
catch (IOException e)
{
message += "\n"
+ exception.getMessage () + '\n'
+ "Could not reset the previous position.";
exception = e;
}
throw IO_Error (message, exception);
}
}
}
/** Get the current source stream position.
@return The current source stream position as a byte offset from the
beginning of the file.
*/
public long Stream_Position ()
{return Stream_Position;}
/** Generate an IOException containing a message.
If the provided message does not already contain the class {@link
#ID} the ID and a NL character is prepended to the message (or the ID
becomes the message if it is null). If a non-null exception is
provided, the message from the exception is appended, after a NL
character, to the message used in constructing the IOException.
If the exception argument is an instance of EOFException the returned
IOException will also be an EOFException. If the exception argument
is non-null and contains a cause, an attempt is made to apply the
cause to the new IOException (failure to apply the cause is ignored).
@param message The message String to be included in the IOException.
@return An IOException.
@see #IOException(String, Exception)
*/
private IOException IO_Error
(
String message,
Exception exception
)
{
if (message == null)
message = ID;
else if (message.indexOf (ID) < 0)
message = ID + '\n' + message;
if (exception != null)
message += "\n" + exception.getMessage ();
IOException
except;
if (exception instanceof EOFException)
except = new EOFException (message);
else
except = new IOException (message);
if (exception != null)
{
Throwable
cause = exception.getCause ();
if (cause != null)
{
try {except.initCause (cause);}
catch (IllegalStateException e) {}
}
}
return except;
}
/** Generate an IOException containing a message.
@param message The message String to be included in the IOException.
@return An IOException.
@see #IOException(String, Exception)
*/
private IOException IO_Error
(
String message
)
{return IO_Error (message, null);}
/*==============================================================================
Parameters
*/
/** Add data position Parameters to a Parameter Group.
A {@link #DATA_POSITION_PARAMETER} is added to the group with the
current {@link #Stream_Position() stream position} as its value. A
{@link #DATA_LENGTH_PARAMETER} is also added to the group with the
number of bytes between the current stream position (inclusive) and
the end position (exclusive) as its value.
N.B.: If {@link #Use_Data_Position(boolean) using data
position parameters} is disabled {@link
#Data_Offset_Parameters(Parameter, long, long) data offset
parameters} will be used instead for the same values.
@param group The Parameter Group (Aggregate) to receive the data
location parameters.
@param end_position The end position in the Source of the data as
a byte offset from the beginning of the file to the byte
immediately following the last byte of the data segement. If this
value is not greater than zero no {@link #DATA_LENGTH_PARAMETER}
is included.
@throws IllegalArgumentException If the current {@link
#Stream_Position() stream position} is greater than the data end
position.
@see #Data_Offset_Parameters(Parameter, long, long)
*/
protected void Data_Position_Parameters
(
Parameter group,
long end_position
)
throws IllegalArgumentException
{
if (end_position > 0 &&
Stream_Position > end_position)
throw new IllegalArgumentException (ID + '\n'
+ "Invalid " + group.Name () + " data position parameter values -\n"
+ " start = " + Stream_Position + '\n'
+ " end = " + end_position);
if (Use_Data_Position)
{
try
{
group
.Add (new Parameter (DATA_POSITION_PARAMETER)
.Value (new Value (Stream_Position)
.Units ("byte offset")));
if (end_position > 0)
group
.Add (new Parameter (DATA_LENGTH_PARAMETER)
.Value (new Value (end_position - Stream_Position)
.Units ("bytes")));
}
catch (PVL_Exception exception) {}
}
else
Data_Offset_Parameters (group, Stream_Position, end_position);
}
/** Add data offset Parameters to a Parameter Group.
A {@link #DATA_OFFSET_PARAMETER} is added to the group followed by a
a {@link #DATA_LENGTH_PARAMETER}.
@param group The Parameter Group (Aggregate) to receive the data
offset parameters.
@param start_offset The offset (in bytes relative to 0) of the
data location - excluding segment marker and length elements - in
the enclosing object.
@param end_offset The offset of the end (byte immediately following
the last data byte) of the data block. If this value is not greater
than zero no {@link #DATA_LENGTH_PARAMETER} is included.
@throws IllegalArgumentException If the data start offser is
greater than the end offset. #Stream_Position() stream position}
is greater than the data end position.
@see #Data_Position_Parameters(Parameter, long)
*/
protected void Data_Offset_Parameters
(
Parameter group,
long start_offset,
long end_offset
)
throws IllegalArgumentException
{
if (end_offset > 0 &&
start_offset > end_offset)
throw new IllegalArgumentException (ID + '\n'
+ "Invalild " + group.Name () + " data offset parameter values -\n"
+ " start = " + start_offset + '\n'
+ " end = " + end_offset);
try
{
group
.Add (new Parameter (DATA_OFFSET_PARAMETER)
.Value (new Value (start_offset).Units ("byte offset")));
if (end_offset > 0)
group
.Add (new Parameter (DATA_LENGTH_PARAMETER)
.Value (new Value (end_offset - start_offset).Units ("bytes")));
}
catch (PVL_Exception exception) {}
}
/** Generate a {@link #VALUE_BITS_PARAMETER} from the source.
Signed byte values are read from the Source starting at the current
{@link #Stream_Position() stream position} up to, but not including,
the end position. The value is incremented by 1. If the byte value
read is negative only the least significant 7 bits are valid; the
resultant value is the negative of the value of these bits. A
negative value signals that the values whose bit precision is the
absolute of the value is a signed value. A value of zero signals that
the actual precision values are indictated elsewhere.
Each value read is added to an Array Value that is assigned to a
Parameter named {@link #VALUE_BITS_PARAMETER} which is what is
returned.
@param description A String describing the values being obtained.
@param end_position The end position in the Source of the values
as a byte offset from the beginning of the file to the byte
immediately following the last byte to be read.
@return An Assignment Parameter named {@link #VALUE_BITS_PARAMETER}
that has an Array Value with the adjust values read from the Source.
@throws IOException If there was a problem reading from the Source.
*/
protected Parameter Value_Bits_Parameter
(
String description,
long end_position
)
throws IOException
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(">>> JPEG2000_Info.Value_Bits_Parameter: " + description + '\n'
+" From stream position " + Stream_Position + '\n'
+" Until stream position " + end_position);
String
describe = description + ' ' + VALUE_BITS_PARAMETER;
Parameter
parameter = null;
try {
Value
list = new Value ().Type (Value.SEQUENCE);
int
datum;
while (Stream_Position < end_position)
{
datum = Read_byte (describe) + 1;
if (datum < 0)
datum = -(datum & 0x7F);
list.Add (new Value (datum));
}
parameter = new Parameter (VALUE_BITS_PARAMETER)
.Comments
("\nNegative bits indicate signed values of abs (bits);\n"
+" Zero bits indicate variable number of bits.")
.Value (list);
}
catch (PVL_Exception exception) {}
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
("<<< JPEG2000_Info.Value_Bits_Parameter: "
+ parameter.Description ());
return parameter;
}
/** Generate a {@link #VALUE_BITS_PARAMETER} from an Array of raw Values.
The datum of each Value in the array is assumed to be a raw bit
precision value. This value is incremented by 1. If the value is
negative the least significant 7 bits are taken and then negated to
signal that the image values are signed. The image value precision of
each component is the absolute value of the corresponding entry in
the array.
The resultant Array is assigned to a Parameter named {@link
#VALUE_BITS_PARAMETER} which is what is returned.
@param array A Array Value containing raw bit precision values.
@return An Assignment Parameter named {@link #VALUE_BITS_PARAMETER}
that has a Value that is an Array of the adjusted array values.
*/
protected static Parameter Value_Bits_Parameter
(
Value array
)
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(">>> JPEG2000_Info.Value_Bits_Parameter:\n"
+" From Value " + array.Description ());
Parameter
parameter = null;
try {
Value
value;
long
datum;
for (int
index = 0;
index < array.getChildCount ();
index++)
{
value = array.Get (index);
datum = value.long_Data () + 1;
if (datum < 0)
datum = -(datum & 0x7F);
value.Data (datum);
}
parameter = new Parameter (VALUE_BITS_PARAMETER)
.Comments
("\nNegative bits indicate signed values of abs (bits);\n"
+" Zero bits indicate variable number of bits.")
.Value (array);
}
catch (PVL_Exception exception) {}
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
("<<< JPEG2000_Info.Value_Bits_Parameter: "
+ parameter.Description ());
return parameter;
}
/** Get the Array Value of a Parameter as an int array.
@param parameter_name The name of the parameter to use. The first
Parameter found with this name, which may be a pathname, is used.
@return An int array.
@see #int_Array(Parameter)
*/
public int[] int_Array
(
String parameter_name
)
{return int_Array (Find (parameter_name));}
/** Get the Array Value of a Parameter as an int array.
@param parameter The Parameter from which to obtain Array Values.
@return An int array.
@see #int_Array(Value)
*/
public static int[] int_Array
(
Parameter parameter
)
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(">>> JP2_Info.int_Array (Parameter): " +
((parameter == null) ? "null" : parameter.Path_Name ()));
int[]
values = new int[0];
if (parameter != null &&
parameter.Is_Assignment ())
{
try {values = int_Array (parameter.Value ());}
catch (PVL_Exception exception) {}
}
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
("<<< JP2_Info.int_Array (Parameter)");
return values;
}
/** Convert an Array Value to an int array.
Each Integer Value in the Array Value is used to set the respective
value of an int array. Any Value in the Array that is not an Integer
is ignored; Sub-Array Values are not entered.
@param value The Array Value to convert.
@return An int array. N.B.: The number of elements in the
array may be less than the number of Values in the Parameter's
Array if it contains non-Integer Values. If the Parameter is not
an Assignment or its Value is not an Array an empty array will be
returned.
*/
public static int[] int_Array
(
Value value
)
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(">>> JP2_Info.int_Array (Value)");
int[]
values = null;
try {
Value
list;
if (value != null &&
value.Is_Array ())
{
int
index,
count = 0,
total_entries = value.getChildCount ();
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" total_entries = " + total_entries);
values = new int[total_entries];
Value
entry;
for (index = 0;
index < total_entries;
index++)
{
entry = value.Get (index);
if (entry.Is_Integer ())
values[count++] = (int)entry.long_Data ();
}
if (count < index)
{
// Contract the int array.
int[]
int_array = new int[count];
for (index = 0;
index < count;
index++)
int_array[index] = values[index];
values = int_array;
}
}
else
values = new int[0];
}
catch (PVL_Exception exception) {}
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
("<<< JP2_Info.int_Array: " + values);
return values;
}
}
pirl-2.3.8/PIRL/Image_Tools/Polar_Stereographic_Spherical_Projection.java 0000644 0001750 0001750 00000014112 11742733714 026311 0 ustar mathieu mathieu /* Polar_Stereographic_Spherical_Projection
PIRL CVS ID: Polar_Stereographic_Spherical_Projection.java,v 1.3 2012/04/16 06:10:20 castalia Exp
Copyright (C) 2007-2012 Arizona Board of Regents on behalf of the
Planetary Image Research Laboratory, Lunar and Planetary Laboratory at
the University of Arizona.
This file is part of the PIRL Java Packages.
The PIRL Java Packages are free software; you can redistribute them
and/or modify them under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
The PIRL Java Packages are distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see
The conversion algorithm is:
@param image_coordinate The image sample,line coordinate.
@return The world longitude,latitude coordinate. The {@link
Point2D#getX() x} value of the coordinate Point2D is the
longitude; the {@link Point2D#getY() y} value is the latitude.
Values are in degrees within the range 0-360.
*/
public Point2D.Double to_World
(
Point2D image_coordinate
)
throws IllegalArgumentException, ArithmeticException
{
if (image_coordinate == null)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to project image coordinates ("
+ (int)image_coordinate.getX () + ','
+ (int)image_coordinate.getX () + ") to world coordinates\n"
+ "because the image coordinates point is null.");
Point2D.Double
world_coordinate = null;
if (Not_Identity)
{
double
x = Sample_to_Projection_X (image_coordinate.getX ()),
y = Line_to_Projection_Y (image_coordinate.getY ()),
P = StrictMath.sqrt ((x * x) + (y * y)),
C = 2.0 * StrictMath.atan (P / Polar_Radius_times_2);
double
latitude = StrictMath.asin (
(StrictMath.cos (C) * Center_Latitude_Sine)
+ (y * StrictMath.sin (C) * Center_Latitude_Cosine / P));
if (Math.abs (latitude) > PI_OVER_2)
throw new ArithmeticException (ID + '\n'
+ "Projection of image coordinates ("
+ (int)image_coordinate.getX () + ','
+ (int)image_coordinate.getX () + ") to world coordinates\n"
+ "resulted in an invalid latitude of "
+ Math.toDegrees (latitude) + " degrees.");
if (Planetocentric)
latitude = Planetographic_to_Planetocentric (latitude);
latitude = StrictMath.toDegrees (latitude);
double
longitude = Center_Longitude
+ StrictMath.atan (x / -Center_Latitude_Sign * y);
if (Positive_West)
longitude *= -1.0;
longitude = To_360 (StrictMath.toDegrees (longitude));
world_coordinate = new Point2D.Double (longitude, latitude);
}
else
world_coordinate = new Point2D.Double
(image_coordinate.getX (), image_coordinate.getY ());
return world_coordinate;
}
/** Get the image sample,line coordinate for a world longitude,latitude
coordinate.
The conversion algorithm is:
@param world_coordinate The world longitude,latitude coordinate.
The {@link Point2D#getX() x} value of the coordinate Point2D is
the longitude; the {@link Point2D#getY() y} value is the
latitude. Values are in degrees.
@return The image sample,line coordinate.
*/
public Point to_Image
(
Point2D world_coordinate
)
throws IllegalArgumentException
{
if (world_coordinate == null)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to project world coordinates to image coordinates\n"
+ "because the world coordinates point is null.");
Point
image_coordinate = null;
if (Not_Identity)
{
double
longitude = StrictMath.toRadians (world_coordinate.getX ()),
latitude = StrictMath.toRadians (world_coordinate.getY ());
if (Planetocentric)
latitude = Planetographic_to_Planetocentric (latitude);
if (Positive_West)
longitude *= -1.0;
double
rho = Polar_Radius_times_2
* StrictMath.tan (PI_OVER_4
- (Center_Latitude_Sign * 0.5 * latitude)),
distance = longitude - Center_Longitude;
image_coordinate = new Point
(
(int)(Projection_X_to_Sample (rho * StrictMath.sin (distance))
+ 0.5), // Round to nearest pixel.
(int)(Projection_Y_to_Line (rho * StrictMath.cos (distance)
* -Center_Latitude_Sign)
+ 0.5) // Round to nearest pixel.
);
}
else
image_coordinate = new Point
((int)image_coordinate.getX (), (int)image_coordinate.getY ());
return image_coordinate;
}
}
pirl-2.3.8/PIRL/Image_Tools/Makefile 0000644 0001750 0001750 00000001120 10662176534 016760 0 ustar mathieu mathieu # Makefile for Java classes
#
# PIRL CVS ID: Makefile,v 1.3 2007/08/20 02:33:00 castalia Exp
# gmake syntax
JPATH ?= ../..
JC ?= javac
.SUFFIXES: .java .class
.java.class:
${JC} -classpath ${JPATH} ${JFLAGS} $<
CLASSES = Multibuf_ImageInputStream.class \
HTTP_ImageInputStream.class \
JPEG2000_Info.class \
JPEG2000_Codestream_Info.class \
JP2_Info.class \
Projection.class \
Equirectangular_Projection.class \
Polar_Stereographic_Elliptical_Projection.class \
Polar_Stereographic_Spherical_Projection.class
all: ${CLASSES}
clean:
rm -f *.class
pirl-2.3.8/PIRL/Image_Tools/JPEG2000_Codestream_Info.java 0000644 0001750 0001750 00000224367 12052546364 022354 0 ustar mathieu mathieu /* JPEG2000_Codestream_Info
HiRISE CVS ID: JPEG2000_Codestream_Info.java,v 1.32 2012/11/20 00:21:08 castalia Exp
Copyright (C) 2006-2012 Arizona Board of Regents on behalf of the
Planetary Image Research Laboratory, Lunar and Planetary Laboratory at
the University of Arizona.
This file is part of the PIRL Java Packages.
The PIRL Java Packages are free software; you can redistribute them
and/or modify them under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
The PIRL Java Packages are distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see
The JPEG2000 codestream format is defined in Part 1 of the JPEG2000
International Standard (ISO/IEC 15444-1:2004(E); "Information
technology - JPEG 2000 image coding system: Core coding system").
This format is composed entirely of a contiguous sequence of
codestream segment. Each segment is prefaced with a marker that
identifies the segement. The marker is followed by length. Boxes may
be nested within other boxes.
@author Bradford Castalia UA/PIRL
@version 1.32
@see PIRL.Image_Tools.JP2_Info
@see PIRL.Image_Tools.JPEG2000_Info
*/
public class JPEG2000_Codestream_Info
extends JPEG2000_Info
{
public static final String
ID = "PIRL.Image_Tools.JPEG2000_Codestream_Info (1.32 2012/11/20 00:21:08)";
//! The name of this Parameter Aggregate.
public static final String
CODESTREAM = "Codestream";
//! Marker codes.
public static final int
RESERVED_DELIMITER_MARKER_MIN = 0xFF30,
RESERVED_DELIMITER_MARKER_MAX = 0xFF3F,
SOC_MARKER = 0xFF4F,
SOT_MARKER = 0xFF90,
SOD_MARKER = 0xFF93,
EOC_MARKER = 0xFFD9,
SIZ_MARKER = 0xFF51,
COD_MARKER = 0xFF52,
COC_MARKER = 0xFF53,
RGN_MARKER = 0xFF5E,
QCD_MARKER = 0xFF5C,
QCC_MARKER = 0xFF5D,
POC_MARKER = 0xFF5F,
TLM_MARKER = 0xFF55,
PLM_MARKER = 0xFF57,
PLT_MARKER = 0xFF58,
PPM_MARKER = 0xFF60,
PPT_MARKER = 0xFF61,
SOP_MARKER = 0xFF91,
EPH_MARKER = 0xFF92,
CRG_MARKER = 0xFF63,
COM_MARKER = 0xFF64;
//! Marker names.
public static final String
// Delimiting markers and marker segments.
SOC_NAME = "Start_of_Codestream",
SOT_NAME = "Start_of_Tile_Part",
SOD_NAME = "Start_of_Data",
EOC_NAME = "End_of_Codestream",
// Fixed information marker segments.
SIZ_NAME = "Size",
// Functional marker segments.
COD_NAME = "Coding_Style_Default",
COC_NAME = "Coding_Style_Component",
RGN_NAME = "Region_of_Interest",
QCD_NAME = "Quantization_Default",
QCC_NAME = "Quantization_Component",
POC_NAME = "Progression_Order_Change",
// Pointer marker segments.
TLM_NAME = "Tile_Lengths",
PLM_NAME = "Packet_Length_Main",
PLT_NAME = "Packet_Length_Tile",
PPM_NAME = "Packed_Packet_Main",
PPT_NAME = "Packed_Packet_Tile",
// In-bit-stream markers and marker segments.
SOP_NAME = "Start_of_Packet",
EPH_NAME = "End_of_Packet_Header",
// Information marker segments.
CRG_NAME = "Component_Registration",
COM_NAME = "Comment";
private static Hashtable
Marker_Names = new Hashtable ();
static
{
Marker_Names.put (new Integer (SOC_MARKER), SOC_NAME);
Marker_Names.put (new Integer (SOT_MARKER), SOT_NAME);
Marker_Names.put (new Integer (SOD_MARKER), SOD_NAME);
Marker_Names.put (new Integer (EOC_MARKER), EOC_NAME);
Marker_Names.put (new Integer (SIZ_MARKER), SIZ_NAME);
Marker_Names.put (new Integer (COD_MARKER), COD_NAME);
Marker_Names.put (new Integer (COC_MARKER), COC_NAME);
Marker_Names.put (new Integer (RGN_MARKER), RGN_NAME);
Marker_Names.put (new Integer (QCD_MARKER), QCD_NAME);
Marker_Names.put (new Integer (QCC_MARKER), QCC_NAME);
Marker_Names.put (new Integer (POC_MARKER), POC_NAME);
Marker_Names.put (new Integer (TLM_MARKER), TLM_NAME);
Marker_Names.put (new Integer (PLM_MARKER), PLM_NAME);
Marker_Names.put (new Integer (PLT_MARKER), PLT_NAME);
Marker_Names.put (new Integer (PPM_MARKER), PPM_NAME);
Marker_Names.put (new Integer (PPT_MARKER), PPT_NAME);
Marker_Names.put (new Integer (SOP_MARKER), SOP_NAME);
Marker_Names.put (new Integer (EPH_MARKER), EPH_NAME);
Marker_Names.put (new Integer (CRG_MARKER), CRG_NAME);
Marker_Names.put (new Integer (COM_MARKER), COM_NAME);
}
//! Marker code parameter.
public static final String
MARKER_PARAMETER = "Marker";
//! SOT parameters.
public static final String
TILE_INDEX_PARAMETER = "Tile_Index",
TILE_PART_LENGTH_PARAMETER = "Tile_Part_Length",
TILE_PART_INDEX_PARAMETER = "Tile_Part_Index",
TOTAL_TILE_PARTS_PARAMETER = "Total_Tile_Parts";
//! SIZ parameters.
public static final String
CAPABILITY_PARAMETER = "Capability",
REFERENCE_GRID_WIDTH_PARAMETER = "Reference_Grid_Width",
REFERENCE_GRID_HEIGHT_PARAMETER = "Reference_Grid_Height",
HORIZONTAL_IMAGE_OFFSET_PARAMETER = "Horizontal_Image_Offset",
VERTICAL_IMAGE_OFFSET_PARAMETER = "Vertical_Image_Offset",
TILE_WIDTH_PARAMETER = "Tile_Width",
TILE_HEIGHT_PARAMETER = "Tile_Height",
HORIZONTAL_TILE_OFFSET_PARAMETER = "Horizontal_Tile_Offset",
VERTICAL_TILE_OFFSET_PARAMETER = "Vertical_Tile_Offset",
HORIZONTAL_SAMPLE_SPACING_PARAMETER = "Horizontal_Sample_Spacing",
VERTICAL_SAMPLE_SPACING_PARAMETER = "Vertical_Sample_Spacing";
//! COD parameters.
public static final String
CODING_STYLE_PARAMETER = "Coding_Style",
PROGRESSION_ORDER_PARAMETER = "Progression_Order",
TOTAL_QUALITY_LAYERS_PARAMETER = "Total_Quality_Layers",
MULTIPLE_COMPONENT_TRANSFORM_PARAMETER = "Multiple_Component_Transform",
TOTAL_RESOLUTION_LEVELS_PARAMETER = "Total_Resolution_Levels",
CODE_BLOCK_WIDTH_PARAMETER = "Code_Block_Width",
CODE_BLOCK_HEIGHT_PARAMETER = "Code_Block_Height",
CODE_BLOCK_STYLE_PARAMETER = "Code_Block_Style",
TRANSFORM_PARAMETER = "Transform",
PRECINCT_SIZE_PARAMETER = "Precinct_Size";
//! Coding style bit flag masks.
public static final int
ENTROPY_CODER_FLAG = 1 << 0,
SOP_FLAG = 1 << 1,
EPH_FLAG = 1 << 2;
//! Progression order values.
public static final int
LRCP_PROGRESSION_ORDER = 0,
RLCP_PROGRESSION_ORDER = 1,
RPCL_PROGRESSION_ORDER = 2,
PCRL_PROGRESSION_ORDER = 3,
CPRL_PROGRESSION_ORDER = 4;
public static final String
PROGRESSION_ORDERS[] =
{
"Layer-Resolution-Component-Position",
"Resolution-Layer-Component-Position",
"Resolution-Position-Component-Layer",
"Position-Component-Resolution-Layer",
"Component-Position-Resolution-Layer"
};
//! Code block style bit flag masks.
public static final int
SELECTIVE_ARITHMETIC_BYPASS_FLAG = 1 << 0,
RESET_CONTEXT_PROBABILITIES = 1 << 1,
TERMINATION_FLAG = 1 << 2,
VERTICALLY_CAUSAL_CONTEXT_FLAG = 1 << 3,
PREDICTABLE_TERMINATION_FLAG = 1 << 4,
SEGMENTATION_SYMBOLS_FLAG = 1 << 5;
//! Transform values.
public static final int
TRANSFORM_IRREVERSIBLE = 0,
TRANSFORM_REVERSIBLE = 1;
//! COC parameters.
public static final String
COMPONENT_INDEX_PARAMETER = "Component_Index";
//! RGN parameters.
public static final String
ROI_STYLE_PARAMETER = "ROI_Style",
IMPLICIT_SHIFT_PARAMETER = "Implicit_Shift";
//! QCD parameters.
public static final String
QUANTIZATION_STYLE_PARAMETER = "Quantization_Style",
TOTAL_GUARD_BITS_PARAMETER = "Total_Guard_Bits",
STEP_SIZE_PARAMETER = "Step_Size";
//! Quantization style bit field masks.
public static final int
NO_QUANTIZATION = 0,
QUANTIZATION_SCALAR_DERIVED = 1,
QUANTIZATION_SCALAR_EXPOUNDED = 2;
//! POC parameters.
public static final String
LEVEL_INDEX_PARAMETER = "Level_Index",
LAYER_INDEX_PARAMETER = "Layer_Index";
//! TLM parameters.
public static final String
INDEX_PARAMETER = "Index",
TILE_INDEX_SIZE_PARAMETER = "Tile_Index_Size",
TILE_PART_LENGTH_SIZE_PARAMETER = "Tile_Part_Length_Size";
//! PLM and PLT parameters.
public static final String
PACKET_LENGTH_PARAMETER = "Packet_Length",
CONTINUATION_PARAMETER = "Continuation";
// PLM and PLT continuation state variables.
private Parameter
PLM_Packet_Length_Parameter = null,
PLT_Packet_Length_Parameter = null;
private long
PLM_Packet_Length = 0,
PLT_Packet_Length = 0,
PLM_Packet_Length_Bytes_Remaining = 0,
PLT_Packet_Length_Bytes_Remaining = 0;
//! CRG parameters.
public static final String
HORIZONTAL_COMPONENT_OFFSET_PARAMETER = "Horizontal_Component_Offset",
VERTICAL_COMPONENT_OFFSET_PARAMETER = "Vertical_Component_Offset";
//! COM parameters.
public static final String
DATA_TYPE_PARAMETER = "Data_Type",
BINARY_DATA_PARAMETER = "Binary_Data",
TEXT_DATA_PARAMETER = "Text_Data";
//! Data type values.
public static final int
DATA_TYPE_BINARY = 0,
DATA_TYPE_TEXT = 1;
//------------------------------------------------------------------------------
//! Codestream validity flags.
private int
Codestream_Validity = 0;
/** {@link #Codestream_Validity() Codestream validity} bit mask
for the SOC segment found flag.
*/
public static final int
SOC_FOUND = 1 << 0;
/** {@link #Codestream_Validity() Codestream validity} bit mask
for the SIZ segment found flag.
*/
public static final int
SIZ_FOUND = 1 << 1;
/** {@link #Codestream_Validity() Codestream validity} bit mask
for the COD segment found flag.
*/
public static final int
COD_FOUND = 1 << 2;
/** {@link #Codestream_Validity() Codestream validity} bit mask
for the QCD segment found flag.
*/
public static final int
QCD_FOUND = 1 << 3;
/** {@link #Codestream_Validity() Codestream validity} bit mask
for the EOC segment found flag.
*/
public static final int
EOC_FOUND = 1 << 4;
/** {@link #Codestream_Validity() Codestream validity} value
indicating that a complete codestream with all required segments
were found.
N.B.: The final EOC delimiter is not included as a
required segment as it is usually not searched for.
*/
public static final int
CODESTREAM_COMPLETE = SOC_FOUND |
SIZ_FOUND |
COD_FOUND |
QCD_FOUND;
/** Flag for missing EOC search through the codestream.
If true and the End of Codestream ({@link #EOC_MARKER EOC}) is not
found because the last tile-part segment has a zero length value, the
remaining codestream data will be searched for the EOC marker. If
false this search - which can be very time cosuming for a very large
codestream segment - will not be done and the {@link
#Codestream_Validity() codestream validity value} will not have the
{@link #EOC_FOUND} flag set.
By default the EOC search is disabled.
*/
public static boolean
EOC_Search = false;
/** Flag whether a zero length tile-part was found in the codestream.
*/
private boolean
Zero_Length_Tile_Part = false;
//! Image geometry information.
private long
Reference_Grid_Width = -1,
Reference_Grid_Height = -1,
Image_Width = -1,
Image_Height = -1,
Horizontal_Image_Offset = -1,
Vertical_Image_Offset = -1,
Tile_Width = -1,
Tile_Height = -1,
Horizontal_Tile_Offset = -1,
Vertical_Tile_Offset = -1;
private int[]
Pixel_Height = new int[0],
Pixel_Width = new int[0];
//! Commonly accessed codestream info:
private int
Total_Components = -1,
Total_Tiles = -1,
Total_Quality_Layers = -1,
Progression_Order = -1,
Total_Resolution_Levels = -1,
Transform = -1;
// DEBUG control.
private static final int
DEBUG_OFF = 0,
DEBUG_CONSTRUCTORS = 1 << 0,
DEBUG_ACCESSORS = 1 << 1,
DEBUG_PARAMETERS = 1 << 2,
DEBUG_HELPERS = 1 << 3,
DEBUG_MAIN = 1 << 4,
DEBUG_ALL = -1,
DEBUG = DEBUG_OFF;
/*==============================================================================
Constructors
*/
/** Construct a JPEG2000_Codestream_Info for a named file.
The inclusion of tile segments in the Parameters is controlled by the
{@link JPEG2000_Info#Skip_Tiles_Default} flag.
@param filename The filename from which to obtain the
JPEG2000_Codestream_Info.
@throws IOException If there was a problem reading the file.
@see #Read(long, boolean)
*/
public JPEG2000_Codestream_Info
(
String filename
)
throws IOException
{this (filename, Skip_Tiles_Default);}
/** Construct a JPEG2000_Codestream_Info for a named file.
@param filename The filename from which to obtain the
JPEG2000_Codestream_Info.
@param skip_tiles true if tile segments are not to be included
in the Parameters; false otherwise.
@throws IOException If there was a problem reading the file.
@see #Read(long, boolean)
*/
public JPEG2000_Codestream_Info
(
String filename,
boolean skip_tiles
)
throws IOException
{
super (filename);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> JPEG2000_Codestream_Info: " + filename);
Read (0, Skip_Tiles = skip_tiles);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< JPEG2000_Codestream_Info");
}
/** Construct a JPEG2000_Codestream_Info for a File.
The inclusion of tile segments in the Parameters is controlled by the
{@link JPEG2000_Info#Skip_Tiles_Default} flag.
@param file The File from which to obtain the
JPEG2000_Codestream_Info.
@throws IOException If there was a problem reading the file.
@see #Read(long, boolean)
*/
public JPEG2000_Codestream_Info
(
File file
)
throws IOException
{this (file, Skip_Tiles_Default);}
/** Construct a JPEG2000_Codestream_Info for a File.
@param file The File from which to obtain the
JPEG2000_Codestream_Info.
@param skip_tiles true if tile segments are not to be included
in the Parameters; false otherwise.
@throws IOException If there was a problem reading the file.
@see #Read(long, boolean)
*/
public JPEG2000_Codestream_Info
(
File file,
boolean skip_tiles
)
throws IOException
{
super (file);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> JPEG2000_Codestream_Info: " + file);
Read (0, Skip_Tiles = skip_tiles);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< JPEG2000_Codestream_Info");
}
/** Construct a JPEG2000_Codestream_Info for an ImageInputStream.
The inclusion of tile segments in the Parameters is controlled by the
{@link JPEG2000_Info#Skip_Tiles_Default} flag.
@param image_input_stream The ImageInputStream from which to obtain
the JPEG2000_Codestream_Info.
@throws IOException If there was a problem reading the file.
@see #Read(long, boolean)
*/
public JPEG2000_Codestream_Info
(
ImageInputStream image_input_stream
)
throws IOException
{this (image_input_stream, Skip_Tiles_Default);}
/** Construct a JPEG2000_Codestream_Info for an ImageInputStream.
@param image_input_stream The ImageInputStream from which to obtain
the JPEG2000_Codestream_Info.
@param skip_tiles true if tile segments are not to be included
in the Parameters; false otherwise.
@throws IOException If there was a problem reading the file.
@see #Read(long, boolean)
*/
public JPEG2000_Codestream_Info
(
ImageInputStream image_input_stream,
boolean skip_tiles
)
throws IOException
{
super (image_input_stream);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> JPEG2000_Codestream_Info: " + image_input_stream);
Read (0, Skip_Tiles = skip_tiles);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< JPEG2000_Codestream_Info");
}
/** Construct a JPEG2000_Codestream_Info for an ImageInputStream and
Reads the stream up to an end position.
@param image_input_stream The ImageInputStream containing a JPEG2000
codestream. The stream is presumed to be positioned at the beginning
of the codestream.
@param end_position The byte position (exclusive) in the stream where
the codestream ends.
@param skip_tiles true if tile segments are not to be included
in the Parameters; false otherwise.
@throws IOException If a problem is encountered while reading the stream.
@see #Read(long, boolean)
*/
public JPEG2000_Codestream_Info
(
ImageInputStream image_input_stream,
long end_position,
boolean skip_tiles
)
throws IOException
{
super (image_input_stream);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> JPEG2000_Codestream_Info: " + image_input_stream + '\n'
+" end_position " + end_position);
Read (end_position, Skip_Tiles = skip_tiles);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< JPEG2000_Codestream_Info");
}
/** Construct a an empty JPEG2000_Codestream_Info Object.
Use one of the Source methods to assign a source file. Then use a
Read method to obtain the information parameters.
@see JPEG2000_Info#Source(String)
@see #Read(long, boolean)
*/
public JPEG2000_Codestream_Info ()
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">-< JPEG2000_Codestream_Info");
}
/*==============================================================================
Accessors
*/
/** Read JPEG2000 codestream information from the Source file.
If no Source file has been assigned, nothing is done.
The Source is read from its current position up to, but not
including, the end position. If the end position is 0 the file is
read until an End_of_Codestream segment is found, no more recognized
segments are found, or the end of file. If an unrecognized marker is
encountered the stream is repositioned back to the location where the
marker was read.
Any information Parameters currently present are removed. Then the
file is scanned for JPEG2000 codestream marker segments. Each segment
found is used to define the contents of a Parameter Group added to
the base JPEG2000_Info Aggregate. The name of each Parameter Group is
the name associated with the marker. The Group always contains the
following parameters:
The remaining Parameters in each Group depend on the segment type.
When JP2 information boxes are nested, the corresponding Parameter
Groups are also nested. JPEG2000 codestream (Contiguous_Codestream,
jp2c) boxes contain a Codestream Parameter Group that is defined by a
JPEG2000_Info object.
N.B.: Unless {@link JPEG2000_Info#Throw_Illegal_State(boolean)
illegal state detection} is disabled, a {@link #WARNING_PARAMETER}
will be placed at the end of the Parameter set and further Source
file scanning halted if the previous segment is invalid. The Value of
the warning Parameter will be a String describing the problem.
Possible sources of warning parameters are: The beginning of the
codestream does not contain a valid Start_of_Codestream segment or
the second segment is not a valid Size segment.
@param end_position The location in the Source stream before which
reading is to stop. If 0 reading stops at the first unrecognized
segment marker or the end of file.
@param skip_tiles true if tile segments are not to be included
in the Parameters; false otherwise.
@return This JPEG2000_Codestream_Info.
@throws IOException If there was a problem reading the Source file.
@see JPEG2000_Info
*/
public JPEG2000_Codestream_Info Read
(
long end_position,
boolean skip_tiles
)
throws IOException
{
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(">>> JPEG2000_Codestream_Info.Read");
if (Image_Input_Stream == null)
{
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
("<<< JPEG2000_Codestream_Info.Read: Image_Input_Stream is null");
return this;
}
ByteOrder
byte_order = Image_Input_Stream.getByteOrder ();
if (byte_order != ByteOrder.BIG_ENDIAN)
Image_Input_Stream.setByteOrder (ByteOrder.BIG_ENDIAN);
// Remove any and all current parameters.
Remove_All ();
// Reset all codestream characterization values.
Reset_Codestream_Values ();
try
{
Stream_Position = Image_Input_Stream.getStreamPosition ();
Add_Segments (this, end_position, skip_tiles);
}
catch (IOException exception)
{
throw IO_Error
("Unable to obtain JPEG2000 Codestream Info from Source"
+ " at position " + Stream_Position,
exception);
}
catch (IllegalStateException exception)
{
try {Add (new Parameter (WARNING_PARAMETER)
.Value (exception.getMessage ()));}
catch (PVL_Exception except) {}
}
finally
{
Image_Input_Stream.setByteOrder (byte_order);
}
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
("<<< JPEG2000_Codestream_Info.Read");
return this;
}
/** Read JPEG2000 codestream information from the Source file.
@return This JPEG2000_Codestream_Info.
@throws IOException If there was a problem reading the Source.
@see #Read(long, boolean)
*/
public JPEG2000_Codestream_Info Read ()
throws IOException
{return Read (0, Skip_Tiles);}
/** Test if the Source file contains a complete codestream.
The Source must be {@link #Read(long, boolean) read} for this test to
be valid.
@return true if the {@link #Codestream_Validity() Codestream
Validity} value has all the {@link #CODESTREAM_COMPLETE} flags
set; false otherwise.
*/
public boolean Is_Complete_Codestream ()
{return (Codestream_Validity & CODESTREAM_COMPLETE) == CODESTREAM_COMPLETE;}
/** Get the codestream validity flags.
@return An int value holding the codestream validity flags. This
will be 0 if the value is not yet known.
@see #SIZ_FOUND
@see #COD_FOUND
@see #QCD_FOUND
@see #EOC_FOUND
@see #CODESTREAM_COMPLETE
*/
public int Codestream_Validity ()
{return Codestream_Validity;}
/** Get the total number of components identified in the codestream.
This value corresponds to the value of the {@link
#TOTAL_COMPONENTS_PARAMETER}.
@return The total number of components in the codestream. This will
be -1 if the value is not yet known.
*/
public int Total_Components ()
{return Total_Components;}
/** Get the width of the image.
The image width .
@return The image width in reference grid units. This will be -1
if the value is not yet known.
*/
public long Image_Width ()
{return Image_Width;}
/** Get the height of the image.
This value corresponds to the value of the {@link
#REFERENCE_GRID_HEIGHT_PARAMETER}.
@return The image height in reference grid units. This will be -1
if the value is not yet known.
*/
public long Image_Height ()
{return Image_Height;}
/** Get the width of the image components reference grid.
This value corresponds to the value of the {@link
#REFERENCE_GRID_WIDTH_PARAMETER}.
@return The image components reference grid width. This will be -1
if the value is not yet known.
*/
public long Reference_Grid_Width ()
{return Reference_Grid_Width;}
/** Get the height of the image components reference grid.
This value corresponds to the value of the {@link
#REFERENCE_GRID_HEIGHT_PARAMETER}.
@return The image components reference grid height. This will be -1
if the value is not yet known.
*/
public long Reference_Grid_Height ()
{return Reference_Grid_Height;}
/** Get the horizontal offset of the image on the reference grid.
The horizontal offset to the upper left corner of the image area
will always be positive (to the right relative to the reference grid
origin at the upper left corner of the reference grid). This value
corresponds to the value of the {@link
#HORIZONTAL_IMAGE_OFFSET_PARAMETER}.
@return The horizontal offset of the image on the reference grid.
This will be -1 if the value is not yet known.
*/
public long Horizontal_Image_Offset ()
{return Horizontal_Image_Offset;}
/** Get the vertical offset of the image on the reference grid.
The vertical offset to the upper left corner of the image area will
always be positive (downwards relative to the reference grid origin
at the upper left corner of the reference grid). This value
corresponds to the value of the {@link
#VERTICAL_IMAGE_OFFSET_PARAMETER}.
@return The horizontal offset of the image on the reference grid.
This will be -1 if the value is not yet known.
*/
public long Vertical_Image_Offset ()
{return Vertical_Image_Offset;}
/** Get the width of a component's pixel.
The width of a pixel is measured in reference grid units. Each
component of the image may have a differenct pixel width. This
value array corresponds to the array of the {@link
#HORIZONTAL_SAMPLE_SPACING_PARAMETER}.
@return An int array of pixel width values in component order.
This will be an empty array if the values are not yet known.
*/
public int[] Pixel_Width ()
{return Pixel_Width;}
/** Get the height of a component's pixel.
The height of a pixel is measured in reference grid units. Each
component of the image may have a differenct pixel height. This
value array corresponds to the array of the {@link
#VERTICAL_SAMPLE_SPACING_PARAMETER}.
@return An int array of pixel height values in component order.
This will be an empty array if the values are not yet known.
*/
public int[] Pixel_Height ()
{return Pixel_Height;}
/** Get the tile width.
This value corresponds to the value of the {@link
#TILE_WIDTH_PARAMETER}.
@return The tile width measured in reference grid units. This will
be -1 if the value is not yet known.
*/
public long Tile_Width ()
{return Tile_Width;}
/** Get the tile height.
This value corresponds to the value of the {@link
#TILE_HEIGHT_PARAMETER}.
@return The tile height measured in reference grid units. This will
be -1 if the value is not yet known.
*/
public long Tile_Height ()
{return Tile_Height;}
/** Get the horizontal offset of the tiles on the reference grid.
The horizontal offset to the upper left corner of the upper left
tile will always be positive (to the right relative to the reference
grid origin at the upper left corner of the reference grid) and no
greather than the {@link #Horizontal_Image_Offset() horizontal image
offset}. This value corresponds to the value of the {@link
#HORIZONTAL_IMAGE_OFFSET_PARAMETER}.
@return The horizontal offset of the tiles on the reference grid.
This will be -1 if the value is not yet known.
*/
public long Horizontal_Tile_Offset ()
{return Horizontal_Tile_Offset;}
/** Get the vertical offset of the tiles on the reference grid.
The vertical offset to the upper left corner of the upper left tile
will always be positive (downwards relative to the reference grid
origin at the upper left corner of the reference grid) and no
greather than the {@link #Vertical_Image_Offset() vertical image
offset}. This value corresponds to the value of the {@link
#VERTICAL_IMAGE_OFFSET_PARAMETER}.
@return The horizontal offset of the tiles on the reference grid.
This will be -1 if the value is not yet known.
*/
public long Vertical_Tile_Offset ()
{return Vertical_Tile_Offset;}
/** Get the total tiles expected to be found in the codestream.
@return The total number of tiles expected, but not necessarily
found, in the codestream. This will be -1 if the value is not
yet known.
*/
public int Total_Tiles ()
{return Total_Tiles;}
/** Test if a final tile-part of zero (unknown) length was found in the
codestream.
If a tile-part of zero length is found in the codestream it must be
the last tile-part before the EOC marker. If {@link #EOC_Search} has
been set the tile-part will be searched for the final EOC delimiter
segment.
@return true if a zero length tile-part was found; false otherwise.
*/
public boolean Zero_Length_Tile_Part ()
{return Zero_Length_Tile_Part;}
/** Get the total number of quality layers in the codestream.
This value corresponds to the value of the {@link
#TOTAL_QUALITY_LAYERS_PARAMETER}.
@return The total number of quality layers in the codestream. This
will be -1 if the value is not yet known.
*/
public int Total_Quality_Layers ()
{return Total_Quality_Layers;}
/** Get the codestream default progression order.
Use the {@link #PROGRESSION_ORDERS} String array to obtain a
description of the progression order code.
This value corresponds to the value of the {@link
#PROGRESSION_ORDER_PARAMETER}.
@return The codestream progression order code from the COD segment.
The value may be one of {@link #LRCP_PROGRESSION_ORDER}, {@link
#RLCP_PROGRESSION_ORDER}, {@link #RPCL_PROGRESSION_ORDER},
{@link #PCRL_PROGRESSION_ORDER}, or {@link
#CPRL_PROGRESSION_ORDER}. This will be -1 if the value is not
yet known.
*/
public int Progression_Order ()
{return Progression_Order;}
/** Get the total number of resolution levels.
The value is obtained from the first coding style default (COD)
segment encountered in the codestream. This is expected to be from
the image and tile size (SIZ) segment. But if a tile header is
independently parsed and it contains a COD segment then that will be
used. N.B.: The value is never obtained from a coding style
component (COC) segment. This value corresponds to the value of
the {@link #TOTAL_RESOLUTION_LEVELS_PARAMETER}.
The total number of resolution levels is one more than the maximum
decomposition level.
@return The total number of resolution levels. This will be -1 if
the value is not yet known.
*/
public int Total_Resolution_Levels ()
{return Total_Resolution_Levels;}
/** Get the form of the codestream transformation.
The value is obtained from the first coding style default (COD)
segment encountered in the codestream. This is expected to be from
the image and tile size (SIZ) segment. But if a tile header is
independently parsed and it contains a COD segment then that will
be used. N.B.: The value is never obtained from a coding
style component (COC) segment. This value corresponds to the value
of the {@link #TRANSFORM_PARAMETER}.
@return The codestream transformation indicator. This will be {@link
#TRANSFORM_IRREVERSIBLE} (0) for the 9-7 irreversible filter; it
will be {@link #TRANSFORM_REVERSIBLE} (1) for the 5-3 reversible
filter. This will be -1 if the value is not yet known.
*/
public int Transform ()
{return Transform;}
private void Reset_Codestream_Values ()
{
Codestream_Validity = 0;
Zero_Length_Tile_Part = false;
Reference_Grid_Width =
Reference_Grid_Height =
Image_Width =
Image_Height =
Horizontal_Image_Offset =
Vertical_Image_Offset =
Tile_Width =
Tile_Height =
Horizontal_Tile_Offset =
Vertical_Tile_Offset = -1;
Total_Components =
Total_Tiles =
Total_Quality_Layers =
Progression_Order =
Total_Resolution_Levels =
Transform = -1;
Pixel_Width = new int[0];
Pixel_Height = new int[0];
}
/*==============================================================================
Markers and Marker Segments
*/
/** Assemble a Parameter Aggregate describing a sequence of codestream
segments from a byte array.
A sequence of codestream segments is parsed from the byte data. All
segments found are parsed. {@link
JPEG2000_Info#Use_Data_Position(boolean) Including data position}
parameters is disabled as is {@link
JPEG2000_Info#Throw_Illegal_State(boolean) illegal codestream segment
organizaion detection}.
@param data A byte array.
@param offset The offset where the codestream segments are expected
to start.
@param length The maximum amount of byte data to be read. However,
if the data array ends before length bytes after the starting
offset, then only the available bytes will be read.
@param skip_tiles true if tile segments are not to be included
in the Parameters; false otherwise.
@return A Parameter Aggregate containing Parameters describing the
codestream segment contents. This will be null if the contents of
a recognized segment were not available within the data length.
*/
public static Parameter Segments
(
byte[] data,
int offset,
int length,
boolean skip_tiles
)
{
if (data == null)
return null;
JPEG2000_Codestream_Info
info = new JPEG2000_Codestream_Info ();
info.Source (new MemoryCacheImageInputStream (new ByteArrayInputStream
(data, offset, length)));
info.Source ().setByteOrder (ByteOrder.BIG_ENDIAN);
info.Use_Data_Position (false);
info.Throw_Illegal_State (false);
try {info.Read (0, skip_tiles);}
catch (Exception exception) {}
return (Parameter)info;
}
/** Assemble a Parameter Aggregate describing a sequence of codestream
segments from a byte array.
The {@link #Skip_Tiles_Default} flag determines if tile segments
will be skipped.
@param data A byte array.
@param offset The offset where the codestream segments are expected
to start.
@param length The maximum amount of byte data to be read. However,
if the data array ends before length bytes after the starting
offset, then only the available bytes will be read.
@return A Parameter Aggregate containing Parameters describing the
codestream segment contents. This will be null if the contents of
a recognized segment were not available within the data length.
@see #Segments(byte[], int, int, boolean)
*/
public static Parameter Segments
(
byte[] data,
int offset,
int length
)
{return Segments (data, offset, length, Skip_Tiles_Default);}
/** Assemble a Parameter Aggregate describing a sequence of codestream
segments from a byte array.
@param data A byte array.
@param skip_tiles true if tile segments are not to be included
in the Parameters; false otherwise.
@return A Parameter Aggregate containing Parameters describing the
codestream segment contents. This will be null if the contents of
a recognized segment were not available within the data length.
@see #Segments(byte[], int, int, boolean)
*/
public static Parameter Segments
(
byte[] data,
boolean skip_tiles
)
{return Segments (data, 0, data.length, skip_tiles);}
/** Assemble a Parameter Aggregate describing a sequence of codestream
segments from a byte array.
The {@link #Skip_Tiles_Default} flag determines if tile segments
will be skipped.
@param data A byte array.
@return A Parameter Aggregate containing Parameters describing the
codestream segment contents. This will be null if the contents of
a recognized segment were not available within the data length.
@see #Segments(byte[], int, int, boolean)
*/
public static Parameter Segments
(
byte[] data
)
{return Segments (data, 0, data.length, Skip_Tiles_Default);}
private void Add_Segments
(
Parameter container,
long end_position,
boolean skip_tiles
)
throws IOException, IllegalStateException
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(">>> JPEG2000_Codestream_Info.Add_Segments: To " + container.Name () + '\n'
+" from stream position " + Stream_Position + '\n'
+" until stream position " + end_position + '\n'
+" skip tiles: " + skip_tiles);
Parameter
segment = null;
long
total_tile_parts = 0;
if (end_position <= 0)
end_position = Long.MAX_VALUE;
try
{
Get_Segments:
while (Stream_Position < end_position &&
(segment = Segment_Parameter ()) != null)
{
if (segment.Name ().equals (SOT_NAME))
{
// Start of tile-part.
long
tile_part_end_position = 0;
Parameter
parameter;
try
{
parameter = segment.Find (TILE_PART_LENGTH_PARAMETER);
if (parameter != null)
// The length of the tile-part.
tile_part_end_position = parameter.Value ().long_Data ();
if (tile_part_end_position == 0)
Zero_Length_Tile_Part = true;
else
tile_part_end_position =
Stream_Position
- segment.Find (LENGTH_PARAMETER)
.Value ().long_Data ()
+ tile_part_end_position;
}
catch (PVL_Exception exception)
{
// Should never happen.
segment = null;
break;
}
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" tile-part " + total_tile_parts
+ " end position = " + tile_part_end_position);
if (skip_tiles)
{
if (Zero_Length_Tile_Part)
// Last tile-part before EOC, but unknown length.
segment = Search_for_EOC (end_position);
else
{
// Move forward to the end of the tile-part.
segment = null; // Don't include the tile-part segment.
Stream_Position (tile_part_end_position);
}
break;
}
// Add tile-part segments up to and including the Start_of_Data:
++total_tile_parts;
while (Stream_Position < end_position &&
(parameter = Segment_Parameter ()) != null)
{
try {segment.Add (parameter);}
catch (PVL_Exception exception)
{
// Should never happen.
segment = null;
break Get_Segments;
}
if (parameter.Name ().equals (SOD_NAME))
// Start of bitstream data.
break;
if (tile_part_end_position != 0 &&
tile_part_end_position <= Stream_Position)
// End of tile-part without SOD segment.
break;
}
if (Zero_Length_Tile_Part)
{
// Last tile-part before EOC, but unknown length.
segment = Search_for_EOC (end_position);
break;
}
else
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" Stream_Position after last tile-part segment = "
+ Stream_Position);
if (Stream_Position < tile_part_end_position)
Stream_Position (tile_part_end_position);
}
}
if (segment.Name ().equals (EOC_NAME))
break;
try {container.Add (segment);}
catch (PVL_Exception exception) {}
segment = null;
}
}
catch (EOFException exception)
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" JPEG2000_Codestream_Info.Add_Segments: EOF at stream position "
+ Stream_Position);
}
if (! skip_tiles)
{
// Total tile parts.
try
{
container
.Add (new Parameter (TOTAL_TILE_PARTS_PARAMETER)
.Value (total_tile_parts)
.Comments
("\nTotal number of tile parts found in the codestream."));
if (Total_Tiles > 0 &&
Total_Tiles > total_tile_parts)
container
.Add (new Parameter (WARNING_PARAMETER)
.Value
("At least " + Total_Tiles + " tile parts were expected."));
}
catch (PVL_Exception exception) {}
}
if (segment != null)
{
// Final End of Codestream marker.
try {container.Add (segment);}
catch (PVL_Exception exception) {}
}
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
("<<< JPEG2000_Codestream_Info.Add_Segments");
}
private Parameter Segment_Parameter ()
throws IOException, IllegalStateException
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(">>> JPEG2000_Codestream_Info.Segment_Parameter");
long
segment_position = Stream_Position;
int
marker = Read_Unsigned_short (MARKER_PARAMETER);
long
segment_length =
((marker == SOC_MARKER ||
marker == SOD_MARKER ||
marker == EPH_MARKER ||
marker == EOC_MARKER ||
(marker >= RESERVED_DELIMITER_MARKER_MIN &&
marker <= RESERVED_DELIMITER_MARKER_MAX)) ?
// Delimiting marker; no segment.
2 :
// Segment length.
Read_Unsigned_short (Marker_Name (marker) + ' ' + LENGTH_PARAMETER) + 2),
end_position = segment_position + segment_length;
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" JPEG2000_Codestream_Info.Segment_Parameter: \""
+ Marker_Name (marker)
+ "\" (0x" + Integer.toHexString (marker) + ") -\n"
+" Position = " + segment_position + '\n'
+" Length = " + segment_length);
Parameter
segment = new Parameter (Marker_Name (marker));
try
{
segment
.Add (new Parameter (MARKER_PARAMETER)
.Value (new Value (marker).Base (16)));
if (Use_Data_Position)
segment
.Add (new Parameter (POSITION_PARAMETER)
.Value (new Value (segment_position).Units ("byte offset")));
segment
.Add (new Parameter (LENGTH_PARAMETER)
.Value (new Value (segment_length).Units ("bytes")));
}
catch (PVL_Exception exception) {}
if (Codestream_Validity == 0)
{
// The first marker must be the SOC.
if (marker != SOC_MARKER)
{
if (Throw_Illegal_State)
throw new IllegalStateException (ID + '\n'
+ "Not a valid JPEG2000 codestream: No initial "
+ Marker_Name (SOC_MARKER) + " marker.");
}
else
Codestream_Validity = SOC_FOUND;
}
else if (Codestream_Validity == SOC_FOUND)
{
// The second marker must be the SIZ.
if (marker != SIZ_MARKER)
{
if (Throw_Illegal_State)
throw new IllegalStateException (ID + '\n'
+ "Not a valid JPEG2000 codestream: Missing "
+ Marker_Name (SIZ_MARKER) + " marker.");
}
else
Codestream_Validity |= SIZ_FOUND;
}
if (marker < RESERVED_DELIMITER_MARKER_MIN ||
marker > RESERVED_DELIMITER_MARKER_MIN)
{
switch (marker)
{
// Delimiting markers.
case EOC_MARKER:
Codestream_Validity |= EOC_FOUND;
case SOC_MARKER:
case SOD_MARKER:
case EPH_MARKER:
break;
// Segments.
case SOT_MARKER: SOT_Parameters (segment); break;
case SIZ_MARKER: SIZ_Parameters (segment); break;
case COD_MARKER: COD_Parameters (segment);
Codestream_Validity |= COD_FOUND;
break;
case COC_MARKER: COC_Parameters (segment, end_position); break;
case RGN_MARKER: RGN_Parameters (segment, end_position); break;
case QCD_MARKER: QCD_Parameters (segment, end_position);
Codestream_Validity |= QCD_FOUND;
break;
case QCC_MARKER: QCC_Parameters (segment, end_position); break;
case POC_MARKER: POC_Parameters (segment, end_position); break;
case TLM_MARKER: TLM_Parameters (segment, end_position); break;
case PLM_MARKER: PLM_Parameters (segment, end_position); break;
case PLT_MARKER: PLT_Parameters (segment, end_position); break;
case PPM_MARKER: PPM_Parameters (segment, end_position); break;
case PPT_MARKER: PPT_Parameters (segment, end_position); break;
case SOP_MARKER: SOP_Parameters (segment); break;
case CRG_MARKER: CRG_Parameters (segment, end_position); break;
case COM_MARKER: COM_Parameters (segment, end_position); break;
}
}
if (Stream_Position < end_position)
Stream_Position (end_position);
else
if (Throw_Illegal_State &&
Stream_Position > end_position)
throw new IllegalStateException (ID + '\n'
+ "Invalid " + segment.Name () + " contents -\n"
+ " expected length " + segment_length
+ " but used length " + (Stream_Position - segment_position));
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(((segment == null) ? "" : (segment.Description ()) + '\n')
+"<<< JPEG2000_Codestream_Info.Segment_Parameter: " + segment);
return segment;
}
private void SOT_Parameters
(
Parameter segment
)
throws IOException
{
try {
segment
.Add (new Parameter (TILE_INDEX_PARAMETER)
.Value (Read_Unsigned_short (segment.Name () + ' ' +
TILE_INDEX_PARAMETER)))
.Add (new Parameter (TILE_PART_LENGTH_PARAMETER)
.Value (new Value (Read_Unsigned_int (segment.Name () + ' ' +
TILE_PART_LENGTH_PARAMETER)).Units ("bytes")))
.Add (new Parameter (TILE_PART_INDEX_PARAMETER)
.Value (Read_Unsigned_byte (segment.Name () + ' ' +
TILE_PART_INDEX_PARAMETER)))
.Add (new Parameter (TOTAL_TILE_PARTS_PARAMETER)
.Value (Read_Unsigned_byte (segment.Name () + ' ' +
TOTAL_TILE_PARTS_PARAMETER)));
}
catch (PVL_Exception exception) {}
}
private void SIZ_Parameters
(
Parameter segment
)
throws IOException
{
try {
segment
.Add (new Parameter (CAPABILITY_PARAMETER)
.Value (new Value (Read_Unsigned_short (segment.Name () + ' ' +
CAPABILITY_PARAMETER))
.Base (16)))
.Add (new Parameter (REFERENCE_GRID_WIDTH_PARAMETER)
.Value (Reference_Grid_Width = Read_Unsigned_int (segment.Name () + ' ' +
REFERENCE_GRID_WIDTH_PARAMETER)))
.Add (new Parameter (REFERENCE_GRID_HEIGHT_PARAMETER)
.Value (Reference_Grid_Height = Read_Unsigned_int (segment.Name () + ' ' +
REFERENCE_GRID_HEIGHT_PARAMETER)))
.Add (new Parameter (HORIZONTAL_IMAGE_OFFSET_PARAMETER)
.Value (Horizontal_Image_Offset = Read_Unsigned_int (segment.Name () + ' ' +
HORIZONTAL_IMAGE_OFFSET_PARAMETER)))
.Add (new Parameter (VERTICAL_IMAGE_OFFSET_PARAMETER)
.Value (Vertical_Image_Offset = Read_Unsigned_int (segment.Name () + ' ' +
VERTICAL_IMAGE_OFFSET_PARAMETER)))
.Add (new Parameter (TILE_WIDTH_PARAMETER)
.Value (Tile_Width = Read_Unsigned_int (segment.Name () + ' ' +
TILE_WIDTH_PARAMETER)))
.Add (new Parameter (TILE_HEIGHT_PARAMETER)
.Value (Tile_Height = Read_Unsigned_int (segment.Name () + ' ' +
TILE_HEIGHT_PARAMETER)))
.Add (new Parameter (HORIZONTAL_TILE_OFFSET_PARAMETER)
.Value (Horizontal_Tile_Offset = Read_Unsigned_int (segment.Name () + ' ' +
HORIZONTAL_TILE_OFFSET_PARAMETER)))
.Add (new Parameter (VERTICAL_TILE_OFFSET_PARAMETER)
.Value (Vertical_Tile_Offset = Read_Unsigned_int (segment.Name () + ' ' +
VERTICAL_TILE_OFFSET_PARAMETER)))
.Add (new Parameter (TOTAL_COMPONENTS_PARAMETER)
.Value (Total_Components =
Read_Unsigned_short (segment.Name () + ' ' +
TOTAL_COMPONENTS_PARAMETER)));
Image_Width = Reference_Grid_Width - Horizontal_Image_Offset;
Image_Height = Reference_Grid_Height - Vertical_Image_Offset;
Value
Ssiz = new Value ().Type (Value.SEQUENCE),
XRsiz = new Value ().Type (Value.SEQUENCE),
YRsiz = new Value ().Type (Value.SEQUENCE);
for (int component = 0;
component < Total_Components;
++component)
{
Ssiz.Add (new Value (Read_byte (segment.Name () + ' ' +
VALUE_BITS_PARAMETER + ' ' + component)));
XRsiz.Add (new Value (Read_Unsigned_byte (segment.Name () + ' ' +
HORIZONTAL_SAMPLE_SPACING_PARAMETER + ' ' + component)));
YRsiz.Add (new Value (Read_Unsigned_byte (segment.Name () + ' ' +
VERTICAL_SAMPLE_SPACING_PARAMETER + ' ' + component)));
}
segment
.Add (Value_Bits_Parameter (Ssiz))
.Add (new Parameter (HORIZONTAL_SAMPLE_SPACING_PARAMETER)
.Value (XRsiz))
.Add (new Parameter (VERTICAL_SAMPLE_SPACING_PARAMETER)
.Value (YRsiz));
Pixel_Width = int_Array (XRsiz);
Pixel_Height = int_Array (YRsiz);
Total_Tiles = (int)(
Math.ceil (((double)Reference_Grid_Width - Horizontal_Tile_Offset)
/ Tile_Width) *
Math.ceil (((double)Reference_Grid_Height - Vertical_Tile_Offset)
/ Tile_Height));
}
catch (PVL_Exception exception) {}
}
private void COD_Parameters
(
Parameter segment
)
throws IOException
{
try {
// Scod:
int
Scod = Read_Unsigned_byte (segment.Name () + ' ' + CODING_STYLE_PARAMETER);
segment.Add (new Parameter (CODING_STYLE_PARAMETER)
.Comments ("\nEntropy coder precincts:\n" +
" Precinct size " +
(((Scod & ENTROPY_CODER_FLAG) == 0) ?
"= 32768 x 32768\n" :
("defined in the " + PRECINCT_SIZE_PARAMETER + " parameter.\n")) +
(((Scod & SOP_FLAG) == 0) ? " No " : " ")
+ "SOP marker segments used\n" +
(((Scod & EPH_FLAG) == 0) ? " No " : " ")
+ "EPH marker used")
.Value (new Value (Scod)
.Base (16)));
// SGcod:
Progression_Order = Read_Unsigned_byte (segment.Name () + ' ' +
PROGRESSION_ORDER_PARAMETER);
segment
.Add (new Parameter (PROGRESSION_ORDER_PARAMETER)
.Comments ("\nProgression order:\n " +
((Progression_Order < PROGRESSION_ORDERS.length) ?
PROGRESSION_ORDERS[Progression_Order] : "Unknown"))
.Value (Progression_Order))
.Add (new Parameter (TOTAL_QUALITY_LAYERS_PARAMETER)
.Value (Total_Quality_Layers = Read_Unsigned_short (segment.Name () + ' ' +
TOTAL_QUALITY_LAYERS_PARAMETER)))
.Add (new Parameter (MULTIPLE_COMPONENT_TRANSFORM_PARAMETER)
.Value (Read_Unsigned_byte (segment.Name () + ' ' +
MULTIPLE_COMPONENT_TRANSFORM_PARAMETER)));
// SPcod:
Coding_Style_Parameters (segment, (Scod & ENTROPY_CODER_FLAG) != 0);
// Set the default (highest level) resolution levels and transform type.
Parameter
parameter;
if (Total_Resolution_Levels < 0 &&
(parameter = segment.Find (TOTAL_RESOLUTION_LEVELS_PARAMETER)) != null)
Total_Resolution_Levels = (int)(parameter.Value ().long_Data ());
if (Transform < 0 &&
(parameter = segment.Find (TRANSFORM_PARAMETER)) != null)
Transform = (int)(parameter.Value ().long_Data ());
}
catch (PVL_Exception exception) {}
}
private void COC_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
/*
CAUTION: The size of the COMPONENT_INDEX_PARAMETER is dependent on
the value of Total_Components. If Total_Components has not yet been
set from a COD segment it is not possible to parse this segment.
*/
if (Total_Components < 0)
{
segment.Add (new Parameter (WARNING_PARAMETER)
.Value ("Can not parse COC segment because total components unknown."));
if (Use_Data_Position)
Data_Position_Parameters (segment, end_position);
else
Data_Offset_Parameters (segment,
0, end_position - Stream_Position);
}
else
{
segment.Add (new Parameter (COMPONENT_INDEX_PARAMETER)
.Value ((Total_Components < 257) ?
Read_Unsigned_byte (segment.Name () + ' ' +
COMPONENT_INDEX_PARAMETER) :
Read_Unsigned_short (segment.Name () + ' ' +
COMPONENT_INDEX_PARAMETER)));
// Scoc:
int
Scoc =
Read_Unsigned_byte (segment.Name () + ' ' +
CODING_STYLE_PARAMETER);
segment.Add (new Parameter (CODING_STYLE_PARAMETER)
.Comments ("\nEntropy coder precincts:\n" +
" Precinct size " +
(((Scoc & ENTROPY_CODER_FLAG) == 0) ?
"= 32768 x 32768" :
("defined in the " + PRECINCT_SIZE_PARAMETER + " parameter.")))
.Value (new Value (Scoc)
.Base (16)));
// SPcoc:
Coding_Style_Parameters (segment, (Scoc & ENTROPY_CODER_FLAG) != 0);
}
}
catch (PVL_Exception exception) {}
}
private void Coding_Style_Parameters
(
Parameter segment,
boolean has_precinct_sizes
)
throws IOException
{
try {
int
levels,
datum;
segment
.Add (new Parameter (TOTAL_RESOLUTION_LEVELS_PARAMETER)
.Value (levels = Read_Unsigned_byte (segment.Name () + ' ' +
TOTAL_RESOLUTION_LEVELS_PARAMETER) + 1))
.Add (new Parameter (CODE_BLOCK_WIDTH_PARAMETER)
.Value (1 << ((datum = Read_Unsigned_byte (segment.Name () + ' ' +
CODE_BLOCK_WIDTH_PARAMETER)) + 2))
.Comments ("\nCode-block width exponent offset " + datum + '.'))
.Add (new Parameter (CODE_BLOCK_HEIGHT_PARAMETER)
.Value (1 << ((datum = Read_Unsigned_byte (segment.Name () + ' ' +
CODE_BLOCK_HEIGHT_PARAMETER)) + 2))
.Comments ("\nCode-block height exponent offset " + datum + '.'));
datum = Read_Unsigned_byte (segment.Name () + ' ' + CODE_BLOCK_STYLE_PARAMETER);
segment.Add (new Parameter (CODE_BLOCK_STYLE_PARAMETER)
.Comments ("\nCode-block style:\n" +
(((datum & SELECTIVE_ARITHMETIC_BYPASS_FLAG) == 0) ? " No s" : " S") +
"elective arithmetic coding bypass.\n" +
(((datum & RESET_CONTEXT_PROBABILITIES) == 0) ? " No r" : " R") +
"eset of context probabilities on coding pass boundaries.\n" +
(((datum & TERMINATION_FLAG) == 0) ? " No t" : " T") +
"ermination on each coding pass.\n" +
(((datum & VERTICALLY_CAUSAL_CONTEXT_FLAG) == 0) ? " No v" : " V") +
"erticallly causal context.\n" +
(((datum & PREDICTABLE_TERMINATION_FLAG) == 0) ? " No p" : " P") +
"redictable termination.\n" +
(((datum & SEGMENTATION_SYMBOLS_FLAG) == 0) ? " No s" : " S") +
"egmentation symbols are used.")
.Value (new Value (datum).Base (16)));
datum = Read_Unsigned_byte (segment.Name () + ' ' + TRANSFORM_PARAMETER);
segment.Add (new Parameter (TRANSFORM_PARAMETER)
.Comments ("\nWavelet transformation used:\n " +
((datum == TRANSFORM_IRREVERSIBLE) ?
"9-7 irreversible filter." :
((datum == TRANSFORM_REVERSIBLE) ?
"5-3 reversible filter." :
"Unknown")))
.Value (datum));
if (has_precinct_sizes)
{
Value
list = new Value ().Type (Value.SEQUENCE),
pair;
for (int level = 0;
level < levels;
++level)
{
pair = new Value ().Type (Value.SEQUENCE);
datum = Read_Unsigned_byte (segment.Name () + ' ' +
PRECINCT_SIZE_PARAMETER + ' ' + level);
pair
.Add (new Value (1 << (datum & 0x0F)))
.Add (new Value (1 << ((datum & 0xF0) >> 4)));
list.Add (pair);
}
segment.Add (new Parameter (PRECINCT_SIZE_PARAMETER)
.Comments ("\nPrecinct (width, height) by resolution level.")
.Value (list));
}
}
catch (PVL_Exception exception) {}
}
private void RGN_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
/*
CAUTION: The size of the COMPONENT_INDEX_PARAMETER is dependent on
the value of Total_Components. If Total_Components has not yet been
set from a COD segment it is not possible to parse this segment.
*/
if (Total_Components < 0)
{
segment.Add (new Parameter (WARNING_PARAMETER)
.Value ("Can not parse RGN segment because total components unknown."));
if (Use_Data_Position)
Data_Position_Parameters (segment, end_position);
else
Data_Offset_Parameters (segment,
0, end_position - Stream_Position);
}
else
segment
.Add (new Parameter (COMPONENT_INDEX_PARAMETER)
.Value ((Total_Components < 257) ?
Read_Unsigned_byte (segment.Name () + ' ' +
COMPONENT_INDEX_PARAMETER) :
Read_Unsigned_short (segment.Name () + ' ' +
COMPONENT_INDEX_PARAMETER)))
.Add (new Parameter (ROI_STYLE_PARAMETER)
.Value (Read_Unsigned_byte (segment.Name () + ' ' +
ROI_STYLE_PARAMETER)))
.Add (new Parameter (IMPLICIT_SHIFT_PARAMETER)
.Value (Read_Unsigned_byte (segment.Name () + ' ' +
IMPLICIT_SHIFT_PARAMETER)));
}
catch (PVL_Exception exception) {}
}
private void QCD_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{Quantization_Parameters (segment, end_position);}
private void QCC_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
/*
CAUTION: The size of the COMPONENT_INDEX_PARAMETER is dependent on
the value of Total_Components. If Total_Components has not yet been
set from a COD segment it is not possible to parse this segment.
*/
if (Total_Components < 0)
{
segment.Add (new Parameter (WARNING_PARAMETER)
.Value ("Can not parse QCC segment because total components unknown."));
if (Use_Data_Position)
Data_Position_Parameters (segment, end_position);
else
Data_Offset_Parameters (segment,
0, end_position - Stream_Position);
}
else
{
segment.Add (new Parameter (COMPONENT_INDEX_PARAMETER)
.Value ((Total_Components < 257) ?
Read_Unsigned_byte (segment.Name () + ' ' +
COMPONENT_INDEX_PARAMETER) :
Read_Unsigned_short (segment.Name () + ' ' +
COMPONENT_INDEX_PARAMETER)));
Quantization_Parameters (segment, end_position);
}
}
catch (PVL_Exception exception) {}
}
private void Quantization_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
int
datum = Read_Unsigned_byte (segment.Name () + ' ' +
QUANTIZATION_STYLE_PARAMETER),
style = datum & 3;
segment.Add (new Parameter (QUANTIZATION_STYLE_PARAMETER)
.Comments ("\nQuantization:\n " +
((style == NO_QUANTIZATION) ? "None" :
((style == QUANTIZATION_SCALAR_DERIVED) ?
"Scalar derived; values signalled for N-subL LL sub-band only." :
((style == QUANTIZATION_SCALAR_EXPOUNDED) ?
"Scalar expounded; values signalled for each sub-band." :
"Unknown"))))
.Value (style));
segment.Add (new Parameter (TOTAL_GUARD_BITS_PARAMETER)
.Value ((datum & 0xE0) >> 5));
Value
list = new Value ().Type (Value.SEQUENCE),
entry;
while (Stream_Position < end_position)
{
// Exponent
datum = Read_Unsigned_byte (segment.Name () + ' ' + STEP_SIZE_PARAMETER);
if (style == NO_QUANTIZATION)
entry = new Value ((datum & 0xF8) >> 3);
else
{
// Mantissa
entry = new Value ().Type (Value.SEQUENCE);
entry.Add (new Value ((datum & 0xF8) >> 3));
datum <<= 8;
datum |= Read_Unsigned_byte (segment.Name () + ' ' +
STEP_SIZE_PARAMETER);
entry.Add (new Value (datum & 0x07FF));
}
list.Add (entry);
}
segment.Add (new Parameter (STEP_SIZE_PARAMETER)
.Comments ("\n" + ((style == NO_QUANTIZATION) ?
"Reversible transform dynamic range exponent" :
"Irreversible transform quantization step size (exponent, mantissa)")
+ " by sub-band.")
.Value (list));
}
catch (PVL_Exception exception) {}
}
private void POC_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
/*
CAUTION: The size of the COMPONENT_INDEX_PARAMETER is dependent on
the value of Total_Components. If Total_Components has not yet been
set from a COD segment it is not possible to parse this segment.
*/
if (Total_Components < 0)
{
segment.Add (new Parameter (WARNING_PARAMETER)
.Value ("Can not parse POC segment because total components unknown."));
if (Use_Data_Position)
Data_Position_Parameters (segment, end_position);
else
Data_Offset_Parameters (segment,
0, end_position - Stream_Position);
}
else
{
Value
levels = new Value ().Type (Value.SEQUENCE),
components = new Value ().Type (Value.SEQUENCE),
layers = new Value ().Type (Value.SEQUENCE),
progression_orders = new Value ().Type (Value.SEQUENCE),
levels_range,
components_range;
int
datum;
while (Stream_Position < end_position)
{
levels_range = new Value ().Type (Value.SEQUENCE)
.Add (new Value (Read_Unsigned_byte (segment.Name () + ' ' +
LEVEL_INDEX_PARAMETER)));
components_range = new Value ().Type (Value.SEQUENCE)
.Add (new Value ((Total_Components < 257) ?
Read_Unsigned_byte (segment.Name () + ' ' +
COMPONENT_INDEX_PARAMETER) :
Read_Unsigned_short (segment.Name () + ' ' +
COMPONENT_INDEX_PARAMETER)));
layers.Add (new Value (Read_Unsigned_short (segment.Name () + ' ' +
LAYER_INDEX_PARAMETER)));
levels_range.Add (new Value (Read_Unsigned_byte (segment.Name () + ' ' +
LEVEL_INDEX_PARAMETER)));
levels.Add (levels_range);
datum = (Total_Components < 257) ?
Read_Unsigned_byte (segment.Name () + ' ' +
COMPONENT_INDEX_PARAMETER) :
Read_Unsigned_short (segment.Name () + ' ' +
COMPONENT_INDEX_PARAMETER);
if (datum == 0)
datum = 256;
components_range.Add (new Value (datum));
components.Add (components_range);
progression_orders.Add (new Value (Read_Unsigned_byte (segment.Name () + ' ' +
PROGRESSION_ORDER_PARAMETER)));
}
String
comment = "\nIndex (start, end] ranges.";
segment
.Add (new Parameter (LEVEL_INDEX_PARAMETER)
.Comments (comment)
.Value (levels))
.Add (new Parameter (COMPONENT_INDEX_PARAMETER)
.Comments (comment)
.Value (components))
.Add (new Parameter (LAYER_INDEX_PARAMETER)
.Value (layers))
.Add (new Parameter (PROGRESSION_ORDER_PARAMETER)
.Value (progression_orders));
}
}
catch (PVL_Exception exception) {}
}
private void TLM_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
segment.Add (new Parameter (INDEX_PARAMETER)
.Value (Read_Unsigned_byte (segment.Name () + ' ' + INDEX_PARAMETER)));
int
index_size,
length_size = Read_Unsigned_byte (segment.Name () + ' ' +
TILE_INDEX_SIZE_PARAMETER + " and " + TILE_PART_LENGTH_SIZE_PARAMETER);
length_size >>= 4;
index_size = length_size & 0x3;
length_size = (((length_size >> 2) & 0x3) + 1) * 2;
segment
.Add (new Parameter (TILE_INDEX_SIZE_PARAMETER)
.Value (new Value (index_size).Units ("bytes")))
.Add (new Parameter (TILE_PART_LENGTH_SIZE_PARAMETER)
.Value (new Value (length_size).Units ("bytes")));
Value
indices = new Value ().Type (Value.SEQUENCE),
lengths = new Value ().Type (Value.SEQUENCE).Units ("bytes");
while (Stream_Position < end_position)
{
if (index_size != 0)
indices.Add (new Value ((index_size == 1) ?
Read_Unsigned_byte (segment.Name () + ' ' +
TILE_INDEX_PARAMETER) :
Read_Unsigned_short (segment.Name () + ' ' +
TILE_INDEX_PARAMETER)));
lengths.Add (new Value ((length_size == 2) ?
Read_Unsigned_short (segment.Name () + ' ' +
TILE_PART_LENGTH_PARAMETER) :
Read_Unsigned_int (segment.Name () + ' ' +
TILE_PART_LENGTH_PARAMETER)));
}
if (index_size != 0)
segment.Add (new Parameter (TILE_INDEX_PARAMETER)
.Value (indices));
segment.Add (new Parameter (TILE_PART_LENGTH_PARAMETER)
.Value (lengths));
}
catch (PVL_Exception exception) {}
}
private void PLM_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
segment.Add (new Parameter (INDEX_PARAMETER)
.Value (Read_Unsigned_byte (segment.Name () + ' ' + INDEX_PARAMETER)));
Value
lengths;
if (PLM_Packet_Length_Parameter == null)
// First PLM segment; add the new packet lengths parameter and array.
segment.Add (PLM_Packet_Length_Parameter =
new Parameter (PACKET_LENGTH_PARAMETER)
.Value (lengths =
new Value ().Type (Value.SEQUENCE).Units ("bytes")));
else
{
// Continuation PLM segment; append to the existing lengths array.
lengths = PLM_Packet_Length_Parameter.Value ();
segment.Add (new Parameter (CONTINUATION_PARAMETER)
.Value ("true"));
}
long
datum;
while (Stream_Position < end_position)
{
if (PLM_Packet_Length_Bytes_Remaining == 0)
PLM_Packet_Length_Bytes_Remaining =
Read_Unsigned_byte (segment.Name () + " byte count");
datum = Read_Unsigned_byte (segment.Name () + ' ' + PACKET_LENGTH_PARAMETER);
--PLM_Packet_Length_Bytes_Remaining;
PLM_Packet_Length <<= 7;
PLM_Packet_Length |= datum & 0x7F;
if (PLM_Packet_Length_Bytes_Remaining == 0)
{
lengths.Add (new Value (PLM_Packet_Length));
PLM_Packet_Length = 0;
}
}
}
catch (PVL_Exception exception) {}
}
private void PLT_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
segment.Add (new Parameter (INDEX_PARAMETER)
.Value (Read_Unsigned_byte (segment.Name () + ' ' + INDEX_PARAMETER)));
Value
lengths;
if (PLT_Packet_Length_Parameter == null)
// First PLT segment; add the new packet lengths parameter and array.
segment.Add (PLT_Packet_Length_Parameter =
new Parameter (PACKET_LENGTH_PARAMETER)
.Value (lengths =
new Value ().Type (Value.SEQUENCE).Units ("bytes")));
else
{
// Continuation PLT segment; append to the existing lengths array.
lengths = PLT_Packet_Length_Parameter.Value ();
segment.Add (new Parameter (CONTINUATION_PARAMETER)
.Value ("true"));
}
long
datum;
while (Stream_Position < end_position)
{
datum = Read_Unsigned_byte (segment.Name () + ' ' + PACKET_LENGTH_PARAMETER);
PLT_Packet_Length <<= 7;
PLT_Packet_Length |= datum & 0x7F;
if ((PLT_Packet_Length_Bytes_Remaining = (datum & 0x80)) == 0)
{
lengths.Add (new Value (PLT_Packet_Length));
PLT_Packet_Length = 0;
}
}
}
catch (PVL_Exception exception) {}
}
private void PPM_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
segment.Add (new Parameter (INDEX_PARAMETER)
.Value (Read_Unsigned_byte (segment.Name () + ' ' + INDEX_PARAMETER)));
if (Use_Data_Position)
Data_Position_Parameters (segment, end_position);
else
Data_Offset_Parameters (segment,
1, end_position - Stream_Position);
}
catch (PVL_Exception exception) {}
}
private void PPT_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
segment.Add (new Parameter (INDEX_PARAMETER)
.Value (Read_Unsigned_byte (segment.Name () + ' ' + INDEX_PARAMETER)));
if (Use_Data_Position)
Data_Position_Parameters (segment, end_position);
else
Data_Offset_Parameters (segment,
1, end_position - Stream_Position);
}
catch (PVL_Exception exception) {}
}
private void SOP_Parameters
(
Parameter segment
)
throws IOException
{
try {
segment.Add (new Parameter (INDEX_PARAMETER)
.Value (Read_Unsigned_short (segment.Name () + ' ' + INDEX_PARAMETER)));
}
catch (PVL_Exception exception) {}
}
private void CRG_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
Value
horizontal_offsets = new Value ().Type (Value.SEQUENCE),
vertical_offsets = new Value ().Type (Value.SEQUENCE);
while (Stream_Position < end_position)
{
horizontal_offsets.Add (new Value (Read_Unsigned_short (segment.Name () + ' ' +
HORIZONTAL_COMPONENT_OFFSET_PARAMETER)));
vertical_offsets.Add (new Value (Read_Unsigned_short (segment.Name () + ' ' +
VERTICAL_COMPONENT_OFFSET_PARAMETER)));
}
segment
.Add (new Parameter (HORIZONTAL_COMPONENT_OFFSET_PARAMETER)
.Value (horizontal_offsets)
.Comments ("\nOffset in units of 1/65536 of the "
+ HORIZONTAL_SAMPLE_SPACING_PARAMETER + " by component."))
.Add (new Parameter (VERTICAL_COMPONENT_OFFSET_PARAMETER)
.Value (vertical_offsets)
.Comments ("\nOffset in units of 1/65536 of the "
+ VERTICAL_SAMPLE_SPACING_PARAMETER + " by component."));
}
catch (PVL_Exception exception) {}
}
private void COM_Parameters
(
Parameter segment,
long end_position
)
throws IOException
{
try {
int
datum;
segment.Add (new Parameter (DATA_TYPE_PARAMETER)
.Value (datum = Read_Unsigned_short (segment.Name () + ' ' +
DATA_TYPE_PARAMETER)));
if (datum == DATA_TYPE_TEXT)
segment.Add (new Parameter (TEXT_DATA_PARAMETER)
.Value (new Value (Read_String (segment.Name (), end_position))
.Type (Value.TEXT)));
else
{
// DATA_TYPE_BINARY
Value
sequence = new Value ().Type (Value.SEQUENCE);
for (long index = Stream_Position ();
index < end_position;
++index)
sequence.Add (new Value (Read_Unsigned_byte (segment.Name () + ' ' +
BINARY_DATA_PARAMETER)).Base (16));
segment.Add (new Parameter (BINARY_DATA_PARAMETER)
.Value (sequence));
}
}
catch (PVL_Exception exception) {}
}
private Parameter Search_for_EOC
(
long end_position
)
throws IOException
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(">>> JPEG2000_Codestream_Info.Search_for_EOC:\n"
+" from position " + Stream_Position + '\n'
+" to position " + end_position);
if (! EOC_Search)
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" EOC_Search disabled\n"
+"<<< JPEG2000_Codestream_Info.Search_for_EOC");
return null;
}
Parameter
segment = null;
while (Stream_Position < end_position)
{
if (Read_Unsigned_byte (EOC_NAME + " MSB") == (EOC_MARKER >>> 8) &&
Read_Unsigned_byte (EOC_NAME + " LSB") == (EOC_MARKER & 0xFF))
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" EOC found at position " + (Stream_Position - 2));
Codestream_Validity |= EOC_FOUND;
segment = new Parameter (EOC_NAME);
try
{
segment
.Add (new Parameter (MARKER_PARAMETER)
.Value (new Value (EOC_MARKER).Base (16)));
if (Use_Data_Position)
segment
.Add (new Parameter (POSITION_PARAMETER)
.Value (new Value (Stream_Position - 2)
.Units ("byte offset")));
segment
.Add (new Parameter (LENGTH_PARAMETER)
.Value (new Value (2).Units ("bytes")));
}
catch (PVL_Exception exception) {}
break;
}
}
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
("<<< JPEG2000_Codestream_Info.Search_for_EOC");
return segment;
}
/*==============================================================================
Helpers
*/
public static String Marker_Name
(
int marker
)
throws IOException
{
String
string = (String)Marker_Names.get (new Integer (marker));
if (string == null)
string = UNKNOWN;
return string;
}
private IOException IO_Error
(
String message,
Exception exception
)
{
if (message == null)
message = ID;
else if (message.indexOf (ID) < 0)
message = ID + '\n' + message;
if (exception != null)
message += "\n" + exception.getMessage ();
IOException
except = new IOException (message);
if (exception != null)
{
Throwable
cause = exception.getCause ();
if (cause != null)
{
try {except.initCause (cause);}
catch (IllegalStateException e) {}
}
}
return except;
}
private IOException IO_Error
(
String message
)
{return IO_Error (message, null);}
/*==============================================================================
Main
*/
//! Exit status values.
public static final int
SUCCESS = 0,
SYNTAX_ERROR = 1,
IO_EXCEPTION = 2,
NO_INFO = 3,
PVL_ERROR = 4;
/** Report the JPEG2000 codestream segments found in a raw codestream
file.
@param arguments The arguments String array.
@see #Usage()
*/
public static void main
(
String[] arguments
)
{
if ((DEBUG & DEBUG_MAIN) != 0)
System.out.println
("*** " + ID);
boolean
skip_tiles = true,
EOC_search = false,
GUI = false;
String
source = null;
Vector
names = new Vector (),
patterns = new Vector ();
for (int argument = 0;
argument < arguments.length;
++argument)
{
if (arguments[argument].startsWith ("-") &&
arguments[argument].length () > 1)
{
switch (arguments[argument].charAt (1))
{
case 'N':
case 'n':
int
index = arguments[argument].indexOf ('_');
if (index < 0)
{
System.out.println
("Unknown option: " + arguments[argument]);
Usage ();
}
switch (arguments[argument].charAt (++index))
{
case 'T':
case 't':
skip_tiles = true;
break;
case 'E':
case 'e':
EOC_search = false;
break;
default:
System.out.println
("Unknown option: " + arguments[argument]);
}
break;
case 'T':
case 't':
skip_tiles = false;
break;
case 'E':
case 'e':
EOC_search = true;
break;
case 'F':
case 'f':
if (++argument == arguments.length)
Usage ();
names.add (arguments[argument]);
break;
case 'P':
case 'p':
if (++argument == arguments.length)
Usage ();
patterns.add (arguments[argument]);
break;
case 'G':
case 'g':
GUI = true;
break;
default:
System.out.println
("Unknown option: " + arguments[argument]);
case 'H':
case 'h':
Usage ();
}
}
else if (source == null)
source = arguments[argument];
else
{
System.err.println ("Only one source, please.");
Usage ();
}
}
if (source == null)
{
System.err.println ("A source must be specified.");
Usage ();
}
// Get the Info.
JPEG2000_Codestream_Info
info = null;
JPEG2000_Codestream_Info.EOC_Search = EOC_search;
try {info = new JPEG2000_Codestream_Info (source, skip_tiles);}
catch (Exception exception)
{
System.out.println (exception.getMessage ());
System.exit (IO_EXCEPTION);
}
// Report the Info.
if (info == null)
{
System.out.println ("No JPEG2000 Codestream Info");
System.exit (NO_INFO);
}
int
validity = info.Codestream_Validity ();
boolean
EOC_missing =
((! info.Skip_Tiles ()) &&
((validity & JPEG2000_Codestream_Info.EOC_FOUND) == 0)) ||
(info.Zero_Length_Tile_Part () &&
JPEG2000_Codestream_Info.EOC_Search);
if (! info.Is_Complete_Codestream () ||
EOC_missing)
{
System.out.println (">>> WARNING <<< Incomplete JPEG2000 codestream.\n");
if ((validity & JPEG2000_Codestream_Info.SOC_FOUND) == 0)
System.out.println (" Start of Codestream marker not found.");
if ((validity & JPEG2000_Codestream_Info.SIZ_FOUND) == 0)
System.out.println (" Size marker not found.");
if ((validity & JPEG2000_Codestream_Info.COD_FOUND) == 0)
System.out.println (" Coding Style Default marker not found.");
if ((validity & JPEG2000_Codestream_Info.QCD_FOUND) == 0)
System.out.println (" Quantization Default marker not found.");
if (EOC_missing)
System.out.println (" End of Codestream marker not found.");
System.out.println ();
}
if (! names.isEmpty () ||
! patterns.isEmpty ())
{
Parameter
select = new Parameter (),
parameter;
Selector
criteria;
String
name;
int
root_name_length = info.Name ().length () + 1;
Iterator
list;
if (! names.isEmpty ())
{
criteria = new Selection ().Name (true).Specific (false);
list = names.iterator ();
while (list.hasNext ())
{
select.Name ((String)list.next ());
parameter = null;
while ((parameter = info.Find (select, criteria, parameter))
!= null)
{
name = parameter.Name ();
parameter.Name (parameter.Path_to_Name ()
.substring (root_name_length) + name);
try {parameter.Write ();}
catch (Exception exception)
{
System.out.println
("PVL error -\n" + exception.getMessage () + "\n");
System.exit (PVL_ERROR);
}
parameter.Name (name);
}
}
}
if (! patterns.isEmpty ())
{
criteria = new Selection ().Name (true).Pattern_Match (true);
list = patterns.iterator ();
while (list.hasNext ())
{
select.Name ((String)list.next ());
parameter = null;
while ((parameter = info.Find (select, criteria, parameter))
!= null)
{
name = parameter.Name ();
parameter.Name (parameter.Path_to_Name ()
.substring (root_name_length) + name);
try {parameter.Write ();}
catch (Exception exception)
{
System.out.println
("PVL error -\n" + exception.getMessage () + "\n");
System.exit (PVL_ERROR);
}
parameter.Name (name);
}
}
}
}
else if (GUI)
{
Parameter_View
view = new Parameter_View (info);
view.setVisible (true);
}
else
{
System.out.println (info.Description ());
System.exit (SUCCESS);
}
}
/** Print the command line usage syntax.
JPEG2000_Codestream_Info
[-[No_]Tiles]
[-Gui]
[-Find <parameter>]
[-Pattern <regex>]
<source>
The contents of the specified file are scanned for raw (not contained
within a JP2 file) JPEG2000 codestream segments. The information
found is reported in the form of PVL parameters containing all the
data element values.
N.B.This method always results in a System.exit with a status
of 1.
*/
public static void Usage ()
{
System.out.println
(
ID + '\n' +
"Usage: JP2_Info [
The buffer list is thread-safe.
@author Bradford Castalia UA/PIRL
@version 1.8
@see javax.imageio.stream.ImageInputStream
*/
public class Multibuf_ImageInputStream
extends ImageInputStreamImpl
{
public static final String
ID = "PIRL.Image_Tools.Multibuf_ImageInputStream (1.8 2012/04/16 06:10:20)";
/*------------------------------------------------------------------------------
Buffer Management
*/
/** The list of ByteBuffers that provide the data source.
*/
private List
Data_Buffers = Collections.synchronizedList (new Vector ());
/** Current image data buffer.
The Data_Buffer contains the current data accessed by the
ImageInputStream interface. It's position is where the next
ImageInputStream read byte will be obtained; this is equivalent to
the virtual stream location. It's limit is the end of valid source
data in the buffer (the buffer may not be full to capacity).
*/
protected ByteBuffer
Data_Buffer = null;
/** The index of the Data_Buffer in the Data_Buffers.
*/
private int
Buffer_Index = 0;
/* !!! Workaround !!!
The reset mehod of ImageInputStreamImpl throws an exception if the
position popped from the markByteStack is located before the
flushedPos (beginning of the buffer). This implementation allows
seeking to a location before the beginning of the buffer. The
workaround is to leave the flushedPos at zero and use an alternate
variable for the buffer stream location.
*/
/** Virtual stream location of the Data_Buffer
The first byte of the buffer is located at Buffer_Location offset in
the stream.
*/
protected long
Buffer_Location = 0;
/** Total size (bytes) of all buffers in the list that constitute the
source data stream.
*/
private long
Stream_Size = 0; // Sum of all buffer content amounts.
//------------------------------------------------------------------------------
// DEBUG control
private static final int
DEBUG_OFF = 0,
DEBUG_CONSTRUCTORS = 1 << 0,
DEBUG_ACCESSORS = 1 << 1,
DEBUG_ALL = -1,
DEBUG = DEBUG_OFF;
/*==============================================================================
Constructors
*/
/** Construct a Multibuf_ImageInputStream on a List of ByteBuffers.
@param buffers The List of ByteBuffers to use to use as the data source
in the order they occur in the List.
@throws IllegalArgumentException If the List contains a non-null
Object that is not a.ByteBuffer instance.
@see #Add(ByteBuffer)
*/
public Multibuf_ImageInputStream
(
List buffers
)
throws IllegalArgumentException
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> Multibuf_ImageInputStream: " + buffers);
if (buffers != null)
{
for (int
index = 0;
index < buffers.size ();
index++)
{
Object
buffer = buffers.get (index);
if (buffer != null &&
! (buffer instanceof ByteBuffer))
throw new IllegalArgumentException (ID + '\n'
+ "Can't construct a Multibuf_ImageInputStream from a List\n"
+ "where entry " + index + '/' + buffers.size ()
+ " is not a ByteBuffer.");
Add ((ByteBuffer)buffer);
}
}
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println ("<<< Multibuf_ImageInputStream");
}
/** Construct a Multibuf_ImageInputStream that initial contains a single
ByteBuffer.
@param buffer The ByteBuffer to provide stream data.
@see #Add(ByteBuffer)
*/
public Multibuf_ImageInputStream
(
ByteBuffer buffer
)
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> Multibuf_ImageInputStream: " + buffer);
Add (buffer);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println ("<<< Multibuf_ImageInputStream");
}
/** Construct an empty Multibuf_ImageInputStream.
*/
public Multibuf_ImageInputStream ()
{}
/*==============================================================================
Accessors
*/
/** Add a ByteBuffer to the list of buffers providing stream data.
If the buffer is null or empty (zero limit) it is ignored.
A duplicate of the buffer (pointers are copied, data is not) is
added to the end of the buffers list and rewound (position set
to zero). The {@link #length() length} of the stream is incremented
by the amount of data (limit) in the buffer. If a current buffer
has not be set the new buffer is set as the current buffer.
@param buffer The ByteBuffer to be added to the buffers list.
@return This Multibuf_ImageInputStream.
*/
synchronized public Multibuf_ImageInputStream Add
(
ByteBuffer buffer
)
{
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(">>> Multibuf_ImageInputStream.Add: " + buffer);
if (buffer != null &&
buffer.limit () != 0)
{
Data_Buffers.add (buffer = buffer.duplicate ());
Stream_Size += buffer.rewind ().limit ();
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(" Buffer " + (Data_Buffers.size () - 1)
+ ": adds " + buffer.limit ()
+ " of " + Stream_Size + " bytes.");
if (Data_Buffer == null)
Data_Buffer = buffer;
}
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
("<<< Multibuf_ImageInputStream.Add");
return this;
}
/** Add the contents of another Multibuf_ImageInputStream to this
Multibuf_ImageInputStream.
Each data buffer in the source stream is {@link #Add(ByteBuffer)
Add}ed to the end of the list of data buffers in this stream in the
order in which they are listed.
@return This Multibuf_ImageInputStream.
*/
synchronized public Multibuf_ImageInputStream Add
(
Multibuf_ImageInputStream stream
)
{
for (int
index = 0;
index < stream.Data_Buffers.size ();
index++)
Add ((ByteBuffer)stream.Data_Buffers.get (index));
return this;
}
/** Test if the specified buffer is contained in the buffers list.
Warning: The {@link ByteBuffer#equals(Object)} method is used
to compare the specified buffer against the contents of the buffers
list. This compares the structure and contents of the buffers, not
their object reference values. This can be expensive for large and/or
many buffers. It will also test true if a buffer in the list happens
to have the same content as the specified buffer even if the buffer
objects are different.
@param buffer The ByteBuffer to test for.
@return true if the specified buffer equals some other
*/
public boolean Contains
(
ByteBuffer buffer
)
{return Data_Buffers.contains (buffer);}
/** Remove a buffer from the buffers list.
The indexed buffer is removed from the buffers list and the {@link
#length() length} of the stream decremented by the amount of data
(limit) in the buffer.
If the index of the removed buffer is less than the index of the
current buffer the current {@link
ImageInputStreamImpl#getStreamPosition() stream position} and current
buffer location are decremented by the amount of data in the removed
buffer.
If the index of the removed buffer is equal to the index of the
current buffer the current {@link
ImageInputStreamImpl#getStreamPosition() stream position} is set to
the current buffer location. If there is another buffer in the
buffers list following the removed buffer, the next buffer is set as
the current buffer; thus the fist byte of the next available buffer
will be the next byte read (unless the stream position is {@link
#seek(long) moved}). However, if there is no next buffer - the
removed buffer is at the end of the buffers list - but there is a
buffer in the buffers list immediately preceeding the removed buffer,
then the previous buffer becomes the current buffer and its position
is set to its end (limit); thus the stream position is now st the end
of the stream. Finally, if the removed buffer is the last one in the
buffers list the current buffer is set to null and all pointers are
at zero which is the end of the (now empty) stream.
@param index The index of the buffer to be removed.
@return This Multibuf_ImageInputStream.
@throws ArrayIndexOutOfBoundsException If the specified index is
less than zero or greater than or equal to the size of the
buffers list.
*/
synchronized public Multibuf_ImageInputStream Remove
(
int index
)
throws ArrayIndexOutOfBoundsException
{
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(">>> Multibuf_ImageInputStream.Remove");
if (index >= Data_Buffers.size () ||
index < 0)
throw new ArrayIndexOutOfBoundsException (ID + '\n'
+ "Can't remove buffer at index "
+ index + '/' + Data_Buffers.size () + '.');
ByteBuffer
buffer = (ByteBuffer)Data_Buffers.remove (index);
int
size = buffer.limit ();
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(" Buffer " + index
+ ": removes " + size
+ " of " + Stream_Size + " bytes.\n"
+" Buffer_Index = " + Buffer_Index + '/' + Data_Buffers.size () + '\n'
+" Buffer_Location = " + Buffer_Location + '\n'
+" streamPos = " + streamPos);
Stream_Size -= size;
if (index < Buffer_Index)
{
/* All locations above the removed buffer
shift down by the amount of removed data.
Locations remain attached to the same data.
*/
streamPos -= size;
Buffer_Location -= size;
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(" Buffer_Location = " + Buffer_Location + '\n'
+" streamPos = " + streamPos);
}
else
if (index == Buffer_Index)
{
/* The rug's been removed!
Locations within the range of the removed buffer
are all clamped to the location of the next datum
at the beginning of the next buffer
which has been moved down to the Buffer_Location.
*/
streamPos = Buffer_Location;
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(" streamPos = " + streamPos);
if (Buffer_Index <= Data_Buffers.size ())
{
// Use the next buffer, at the current Buffer_Index.
Data_Buffer = (ByteBuffer)Data_Buffers.get (Buffer_Index);
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(" Using next buffer: " + Data_Buffer);
}
else
{
// There is no next buffer.
if (Previous_Buffer ())
{
// Position at EOF which is Stream_Size.
Data_Buffer.position (Data_Buffer.limit ());
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(" Buffer_Location = " + Buffer_Location + '\n'
+" Using previous buffer: " + Data_Buffer);
}
else
{
/* There is no previous buffer; no buffers remain.
At this point the stream is empty
and all locations are at EOF which is zero.
*/
Data_Buffer = null;
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(" No buffers reamin.");
}
}
}
/*
All locations below the removed buffer
remain unaffected.
*/
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
("<<< Multibuf_ImageInputStream.Remove");
return this;
}
/** Remove the specified buffer from the buffers list.
Warning: The specified buffer is sought using the {@link
List#indexOf(Object)} method on the list of data buffers which
employs the {@link ByteBuffer#equals(Object)} method. See the {@link
#Contains(ByteBuffer) Contains} method for details.
@param buffer The ByteBuffer to be removed.
@return This Multibuf_ImageInputStream.
@see #Remove(int)
*/
public Multibuf_ImageInputStream Remove
(
ByteBuffer buffer
)
{
int
index = Data_Buffers.indexOf (buffer);
if (index >= 0)
Remove (index);
return this;
}
/** Get the List of data buffers backing this object.
Caution: Modifying the contents of the list by reordering or
adding to the List, or changing the amount of valid data in a buffer
(its {@link ByteBuffer#limit(int) limit}) could invalidate the
current {@link ImageInputStream#getStreamPosition() stream position}
and/or {@link #length() stream length} information with indeterminate
(i.e. bad) consequences. Use the {@link #Add(ByteBuffer) Add} and
{@link #Remove(int) Remove} methods to safely manipulate the data
buffer List.
@return The List of ByteBuffer objects backing this
Multibuf_ImageInputStream.
*/
public List Data_Buffers ()
{return Data_Buffers;}
/*==============================================================================
Manipulators
*/
/** Set the next buffer as the current buffer.
A next buffer is present if the current buffer index plus one is less
than the size of the buffers list. In this case the Buffer_Location
is incremented by the amount of data (limit) in the current buffer,
the buffer index is incremented and the correspoding buffer from the
buffer list is set as the current Data_Buffer. It's position is
rewound to zero.
@return true if a next buffer has been set; false if there is no next
buffer.
*/
protected boolean Next_Buffer ()
{
if ((Buffer_Index + 1) >= Data_Buffers.size ())
// Thre is no next buffer.
return false;
// Move the Buffer_Location to the beginning of the next buffer.
Buffer_Location += Data_Buffer.limit ();
// Get the next buffer.
Data_Buffer = (ByteBuffer)Data_Buffers.get (++Buffer_Index);
// Expect sequential reads; seeks will repostion.
Data_Buffer.rewind ();
return true;
}
/** Set the previous data buffer as the current buffer.
If the current buffer index in the buffers list is not zero, the
buffer index is decremented and the corresponding buffer from the
buffer list is set as the current Data_Buffer. It's position
remains unchanged. The Buffer_Location is decremented by the amount
of data (limit) in the new buffer.
@return true if a previous buffer has been set; false if there is no
previous buffer.
*/
protected boolean Previous_Buffer ()
{
if (Buffer_Index == 0)
// There is no previous buffer.
return false;
// Get the previous buffer.
Data_Buffer = (ByteBuffer)Data_Buffers.get (--Buffer_Index);
Buffer_Location -= Data_Buffer.limit ();
return true;
}
/*==============================================================================
ImageInputStream
*/
// Required method.
/** Read a source byte.
The {@link #getBitOffset() bit offset} is set to zero.
@return The next byte value from the source. This will be -1
if the current source location is the end of the stream.
*/
public int read ()
{
int
datum = -1;
if (streamPos < Stream_Size)
{
if (Data_Buffer.remaining () > 0 ||
Next_Buffer ())
{
// Required ImageInputStream functionality.
bitOffset = 0;
++streamPos;
datum = (int)Data_Buffer.get () & 0xFF;
}
}
return datum;
}
// Required method.
/** Read a sequence of source bytes and store them in an array.
The number of bytes actually read may be less than the specified
length. The length will be reduced to the smaller of the amount
of space in the data array following the offset or the amount of
buffered data remaining after an attempt to provide length bytes.
The {@link #getBitOffset() bit offset} is set to zero.
The current source input location is advanced by the amount of
data read.
@param data The byte array into which the data is to be stored.
@param offset The offset of the array where the first byte read is
to be stored.
@param length The number of bytes to read.
@return The number of bytes read and stored. This will be -1 if the
current source location is the end of the stream.
@throws NullPointerException If the data array is null.
@throws IndexOutOfBoundsException If the offset or length are
negative, or the offset is greater than the length of the data
array.
*/
public int read
(
byte[] data,
int offset,
int length
)
{
if (streamPos >= Stream_Size)
return -1;
if (data == null)
throw new NullPointerException (ID + '\n'
+ "Attempt to read into a null data array.");
if (length < 0 ||
offset < 0 ||
offset >= data.length)
throw new IndexOutOfBoundsException (ID + '\n'
+ "Attempt to read into array of length " + data.length
+ " at offset " + offset
+ " for amount " + length + '.');
if ((offset + length) > data.length)
length = data.length - offset;
int
amount = 0;
while (length > 0)
{
int
count = Math.min (length, Data_Buffer.remaining ());
Data_Buffer.get (data, offset, count);
amount += count;
if ((length -= count) == 0 ||
! Next_Buffer ())
break;
offset += count;
}
// Required ImageInputStream functionality.
bitOffset = 0;
streamPos += amount;
return amount;
}
/** Set the current source stream location where the next byte will be read.
The {@link #getBitOffset() bit offset} is set to zero.
@param location The source stream offset for the next read
position. A location less than zero will be set to zero; a
location greater than the source stream size will be set to the
end of the source stream.
*/
public void seek
(
long location
)
{
if (location < Stream_Size)
{
if (location < 0)
location = 0;
// Inter-buffer positioning.
if (location > (Buffer_Location + Data_Buffer.limit ()))
while (Next_Buffer () &&
location > (Buffer_Location + Data_Buffer.limit ()));
else
if (location < Buffer_Location)
while (Previous_Buffer () &&
location < Buffer_Location);
// Intra-buffer positioning.
Data_Buffer.position ((int)(location - Buffer_Location));
streamPos = location;
}
else
streamPos = Stream_Size;
bitOffset = 0;
}
/** Determine if the source data is cached.
@return true
*/
public boolean isCached ()
{return true;}
/** Determine if the source data is cached in memory.
@return true
*/
public boolean isCachedMemory ()
{return true;}
/** Get the total size of all the buffer contents.
@return The size of the source stream.
*/
public long length ()
{return Stream_Size;}
/** Suggests that data before a source location may be discared.
N.B.: No buffered data is ever discared; the suggestion is
ignored.
@param location The source stream offset before which buffered
data may be discarded.
*/
public void flushBefore
(
long location
)
{}
/** Pretends to close the stream.
Nothing is done since the source data is externally owned.
*/
public void close ()
{}
}
pirl-2.3.8/PIRL/Image_Tools/JP2_Info.java 0000644 0001750 0001750 00000172072 12052274645 017545 0 ustar mathieu mathieu /* JP2_Info
HiRISE CVS ID: JP2_Info.java,v 1.39 2012/11/19 00:13:25 castalia Exp
Copyright (C) 2006-2012 Arizona Board of Regents on behalf of the
Planetary Image Research Laboratory, Lunar and Planetary Laboratory at
the University of Arizona.
This file is part of the PIRL Java Packages.
The PIRL Java Packages are free software; you can redistribute them
and/or modify them under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
The PIRL Java Packages are distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see
The JP2 file format is defined in Part 1 of the JPEG2000 International
Standard (ISO/IEC 15444-1:2004(E); "Information technology - JPEG 2000
image coding system: Core coding system"). This file format is composed
entirely of a contiguous sequence of boxes. Each box has a type and
length. Boxes may be nested within other boxes.
@author Bradford Castalia UA/PIRL
@version 1.39
@see PIRL.Image_Tools.JPEG2000_Info
@see PIRL.Image_Tools.JPEG2000_Codestream_Info
*/
public class JP2_Info
extends JPEG2000_Info
{
public static final String
ID = "PIRL.Image_Tools.JP2_Info (1.39 2012/11/19 00:13:25)";
//! Box Type codes.
public static final int
SIGNATURE_TYPE = 0x6A502020,
FILE_TYPE = 0x66747970,
HEADER_TYPE = 0x6A703268,
IMAGE_HEADER_TYPE = 0x69686472,
BITS_PER_COMPONENT_TYPE = 0x62706363,
COLOUR_SPECIFICATION_TYPE = 0x636F6C72,
PALETTE_TYPE = 0x70636C72,
COMPONENT_MAPPING_TYPE = 0x636D6170,
CHANNEL_DEFINITION_TYPE = 0x63646566,
RESOLUTION_TYPE = 0x72657320,
CAPTURE_RESOLUTION_TYPE = 0x72657363,
DEFAULT_DISPLAY_RESOLUTION_TYPE = 0x72657364,
CONTIGUOUS_CODESTREAM_TYPE = 0x6A703263,
INTELLECTUAL_PROPERTY_TYPE = 0x6A703269,
XML_TYPE = 0x786D6C20,
UUID_TYPE = 0x75756964,
UUID_INFO_TYPE = 0x75696E66,
UUID_LIST_TYPE = 0x756C7374,
URL_TYPE = 0x75726C20,
ASSOCIATION_TYPE = 0x61736F63,
LABEL_TYPE = 0X6C626C20,
PLACEHOLDER_TYPE = 0x70686C64;
//! Box names.
public static final String
SIGNATURE_NAME = "Signature",
FILE_NAME = "File_Type",
HEADER_NAME = "JP2_Header",
IMAGE_HEADER_NAME = "Image_Header",
BITS_PER_COMPONENT_NAME = "Bits_Per_Component",
COLOUR_SPECIFICATION_NAME = "Colour_Specification",
PALETTE_NAME = "Palette",
COMPONENT_MAPPING_NAME = "Component_Mapping",
CHANNEL_DEFINITION_NAME = "Channel_Definition",
RESOLUTION_NAME = "Resolution",
CAPTURE_RESOLUTION_NAME = "Capture_Resolution",
DEFAULT_DISPLAY_RESOLUTION_NAME = "Default_Display_Resolution",
CONTIGUOUS_CODESTREAM_NAME = "Contiguous_Codestream",
INTELLECTUAL_PROPERTY_NAME = "Intellectual_Property",
XML_NAME = "XML",
UUID_NAME = "UUID",
UUID_INFO_NAME = "UUID_Info",
UUID_LIST_NAME = "UUID_List",
URL_NAME = "URL",
ASSOCIATION_NAME = "Association",
LABEL_NAME = "Label",
PLACEHOLDER_NAME = "Placeholder";
private static Hashtable
Box_Names = new Hashtable ();
static
{
Box_Names.put (new Integer (SIGNATURE_TYPE),
SIGNATURE_NAME);
Box_Names.put (new Integer (FILE_TYPE),
FILE_NAME);
Box_Names.put (new Integer (HEADER_TYPE),
HEADER_NAME);
Box_Names.put (new Integer (IMAGE_HEADER_TYPE),
IMAGE_HEADER_NAME);
Box_Names.put (new Integer (BITS_PER_COMPONENT_TYPE),
BITS_PER_COMPONENT_NAME);
Box_Names.put (new Integer (COLOUR_SPECIFICATION_TYPE),
COLOUR_SPECIFICATION_NAME);
Box_Names.put (new Integer (PALETTE_TYPE),
PALETTE_NAME);
Box_Names.put (new Integer (COMPONENT_MAPPING_TYPE),
COMPONENT_MAPPING_NAME);
Box_Names.put (new Integer (CHANNEL_DEFINITION_TYPE),
CHANNEL_DEFINITION_NAME);
Box_Names.put (new Integer (RESOLUTION_TYPE),
RESOLUTION_NAME);
Box_Names.put (new Integer (CAPTURE_RESOLUTION_TYPE),
CAPTURE_RESOLUTION_NAME);
Box_Names.put (new Integer (DEFAULT_DISPLAY_RESOLUTION_TYPE),
DEFAULT_DISPLAY_RESOLUTION_NAME);
Box_Names.put (new Integer (CONTIGUOUS_CODESTREAM_TYPE),
CONTIGUOUS_CODESTREAM_NAME);
Box_Names.put (new Integer (INTELLECTUAL_PROPERTY_TYPE),
INTELLECTUAL_PROPERTY_NAME);
Box_Names.put (new Integer (XML_TYPE),
XML_NAME);
Box_Names.put (new Integer (UUID_TYPE),
UUID_NAME);
Box_Names.put (new Integer (UUID_INFO_TYPE),
UUID_INFO_NAME);
Box_Names.put (new Integer (UUID_LIST_TYPE),
UUID_LIST_NAME);
Box_Names.put (new Integer (URL_TYPE),
URL_NAME);
Box_Names.put (new Integer (ASSOCIATION_TYPE),
ASSOCIATION_NAME);
Box_Names.put (new Integer (LABEL_TYPE),
LABEL_NAME);
Box_Names.put (new Integer (PLACEHOLDER_TYPE),
PLACEHOLDER_NAME);
}
//! Box characterization parameter names.
public static final String
NAME_PARAMETER = "Name",
TYPE_PARAMETER = "Type";
//! Signature box parameter.
public static final String
SIGNATURE_PARAMETER = "Signature";
//! Signature value.
public static final int
SIGNATURE = 0x0D0A870A;
//! File Type box parameters.
public static final String
BRAND_PARAMETER = "Brand",
MINOR_VERSION_PARAMETER = "Minor_Version",
COMPATIBILITY_LIST_PARAMETER = "Compatibility";
//! JP2 compatibility value.
public static final String
JP2_COMPATIBLE = "jp2 ";
//! Image Header box parameters.
public static final String
HEIGHT_PARAMETER = "Height",
WIDTH_PARAMETER = "Width",
COMPRESSION_TYPE_PARAMETER = "Compression_Type",
COLORSPACE_UNKNOWN_PARAMETER = "Colorspace_Unknown",
INTELLECTUAL_PROPERTY_PARAMETER = "Intellectual_Property_Rights";
//! Colour Specification box parameters.
public static final String
SPECIFICATION_METHOD_PARAMETER = "Specification_Method",
PRECEDENCE_PARAMETER = "Precedence",
COLOURSPACE_APPROXIMATION_PARAMETER = "Colourspace_Approximation",
ENUMERATED_COLOURSPACE_PARAMETER = "Enumerated_Colourspace";
//! Specification method values.
public static final int
ENUMERATED_COLOURSPACE = 1,
RESTRICTED_ICC_PROFILE = 2;
//! Palette box parameters.
public static final String
ENTRIES_PARAMETER = "Entries",
COLUMNS_PARAMETER = "Columns",
VALUES_PARAMETER = "Values";
//! Component Mapping and Channel Definition parameter.
public static final String
MAP_PARAMETER = "Map";
//! Component map indices.
public static final int
COMPONENT_INDEX = 0,
MAP_TYPE_INDEX = 1,
PALETTE_INDEX = 2;
//! Map type values.
public static final int
DIRECT_USE = 0,
PALETTE_MAPPING = 1;
//! Channel Definition indices.
public static final int
CHANNEL_INDEX = 0,
CHANNEL_TYPE_INDEX = 1,
CHANNEL_ASSOCIATION_INDEX = 2;
//! Channel type values.
public static final int
COLOUR_IMAGE_DATA = 0,
OPACITY = 1,
PREMULTIPLIED_OPACITY = 2;
//! Channel association values.
public static final int
IMAGE_ASSOCIATION = 0,
NO_ASSOCIATION = 0xFFFF;
//! Capture and Default Resolution parameters.
public static final String
VERTICAL_NUMERATOR_PARAMETER = "Vertical_Numerator",
VERTICAL_DENOMINATOR_PARAMETER = "Vertical_Denominator",
VERTICAL_EXPONENT_PARAMETER = "Vertical_Exponent",
HORIZONTAL_NUMERATOR_PARAMETER = "Horizontal_Numerator",
HORIZONTAL_DENOMINATOR_PARAMETER = "Horizontal_Denominator",
HORIZONTAL_EXPONENT_PARAMETER = "Horizontal_Exponent";
//! Codestream parameters.
public static final String
CODESTREAM_PARAMETER = "Codestream";
private JPEG2000_Codestream_Info
Codestream_Info = null;
//! UUID parameter.
public static final String
UUID_PARAMETER = "UUID";
//! UUID value count.
public static final int
NUMBER_OF_UUID_VALUES = 16;
//! URL parameters.
public static final String
VERSION_PARAMETER = "Version",
FLAGS_PARAMETER = "Flags",
URL_PARAMETER = "URL";
//! Text parameters.
public static final String
TEXT_PARAMETER = "Text";
//! JPIP Placeholder parameters.
public static final String
ORIGINAL_BOX_PARAMETER = "Original_Box",
BIN_ID_PARAMETER = "Bin_ID",
EQUIVALENT_BOX_PARAMETER = "Equivalent_Box",
CODESTREAM_ID_PARAMETER = "Codestream_ID",
TOTAL_CODESTREAMS_PARAMETER = "Total_Codestreams",
EXTENDED_BOX_LIST_PARAMETER = "Extended_Box_List";
//! Placeholder box flags value bit masks.
public static final int
PLACEHOLDER_FLAGS_ORIGINAL_MASK = (1 << 0),
PLACEHOLDER_FLAGS_EQUIVALENT_MASK = (1 << 1),
PLACEHOLDER_FLAGS_CODESTREAM_MASK = (1 << 2),
PLACEHOLDER_FLAGS_MULTIPLE_CODESTREAM_MASK = (1 << 3);
//------------------------------------------------------------------------------
//! JP2 file validity flags.
protected int
JP2_Validity = 0;
//! JP2 file validity flags.
public static final int
SIGNATURE_FOUND = 1 << 0,
FILE_TYPE_FOUND = 1 << 1,
JP2_HEADER_FOUND = 1 << 2,
IMAGE_HEADER_FOUND = 1 << 3,
COLOUR_SPECIFICATION_FOUND = 1 << 4,
CONTIGUOUS_CODESTREAM_FOUND = 1 << 5,
JP2_COMPLETE = SIGNATURE_FOUND |
FILE_TYPE_FOUND |
JP2_HEADER_FOUND |
IMAGE_HEADER_FOUND |
COLOUR_SPECIFICATION_FOUND |
CONTIGUOUS_CODESTREAM_FOUND;
// Commonly accessed JP2 info:
private long
Image_Width = -1,
Image_Height = -1;
private int
Total_Components = -1;
private int[]
Bits_per_Component = new int[0];
// DEBUG control.
private static final int
DEBUG_OFF = 0,
DEBUG_CONSTRUCTORS = 1 << 0,
DEBUG_ACCESSORS = 1 << 1,
DEBUG_PARAMETERS = 1 << 2,
DEBUG_HELPERS = 1 << 3,
DEBUG_MAIN = 1 << 4,
DEBUG_ALL = -1,
DEBUG = DEBUG_OFF;
/*==============================================================================
Constructors
*/
/** Construct JP2_Info for a named source.
The inclusion of tile segments in the Parameters is controlled by the
{@link JPEG2000_Info#Skip_Tiles_Default} flag.
@param source The source from which to obtain the JP2_Info.
@throws UnknownHostException If the source is a URL but the
hostname is specifies can not be resolved.
@throws IllegalArgumentException If the source is a URL but does
not specify the http protocol or a source pahtname.
@throws IOException If there was a problem reading the source.
*/
public JP2_Info
(
String source
)
throws IOException, UnknownHostException, IllegalArgumentException
{this (source, Skip_Tiles_Default);}
/** Construct JP2_Info for a named source.
@param source The source from which to obtain the JP2_Info.
@param skip_tiles true if tile segments are not to be included
in the Parameters; false otherwise.
@throws UnknownHostException If the source is a URL but the
hostname is specifies can not be resolved.
@throws IllegalArgumentException If the source is a URL but does
not specify the http protocol or a source pathname.
@throws IOException If there was a problem reading the source.
*/
public JP2_Info
(
String source,
boolean skip_tiles
)
throws IOException, UnknownHostException, IllegalArgumentException
{
super (source);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> JP2_Info: " + source);
Read (Skip_Tiles = skip_tiles);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< JP2_Info");
}
/** Construct JP2_Info for a File.
The inclusion of tile segments in the Parameters is controlled by the
{@link JPEG2000_Info#Skip_Tiles_Default} flag.
@param file The File from which to obtain the JP2_Info.
@throws IOException If there was a problem reading the file.
*/
public JP2_Info
(
File file
)
throws IOException
{this (file, Skip_Tiles_Default);}
/** Construct JP2_Info for a File.
@param file The File from which to obtain the JP2_Info.
@param skip_tiles true if tile segments are not to be included
in the Parameters; false otherwise.
@throws IOException If there was a problem reading the file.
*/
public JP2_Info
(
File file,
boolean skip_tiles
)
throws IOException
{
super (file);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> JP2_Info: " + file);
Read (Skip_Tiles = skip_tiles);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< JP2_Info");
}
/** Construct JP2_Info for an ImageInputStream.
The inclusion of tile segments in the Parameters is controlled by the
{@link JPEG2000_Info#Skip_Tiles_Default} flag.
@param image_input_stream The ImageInputStream from which to obtain
the JP2_Info.
@throws IOException If there was a problem reading the file.
*/
public JP2_Info
(
ImageInputStream image_input_stream
)
throws IOException
{this (image_input_stream, Skip_Tiles_Default);}
/** Construct JP2_Info for an ImageInputStream.
@param image_input_stream The ImageInputStream from which to obtain
the JP2_Info.
@param skip_tiles true if tile segments are not to be included
in the Parameters; false otherwise.
@throws IOException If there was a problem reading the file.
*/
public JP2_Info
(
ImageInputStream image_input_stream,
boolean skip_tiles
)
throws IOException
{
super (image_input_stream);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> JP2_Info: " + image_input_stream);
Read (Skip_Tiles = skip_tiles);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< JP2_Info");
}
/** Construct an empty JP2_Info Object.
Use one of the Source methods to assign a source file. Then use a Read
method to obtain the JP2_Info Parameter set for the file.
@see JPEG2000_Info#Source(String)
@see #Read(boolean)
*/
public JP2_Info ()
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">-< JP2_Info");
}
/*==============================================================================
Accessors
*/
/** Read all available information from the Source file.
If no Source file has been assigned, nothing is done.
The Source is read from the beginning. The Source stream will be
repositioned back to its current position before the method returns.
Any information Parameters currently present are removed. Then the
file is scanned for JP2 information boxes. Each box found is used to
define the contents of a Parameter Group added to the base
JPEG2000_Info Aggregate. The name of each Parameter Group is the JP2
box type composed of four characters (unprintable characters are
represented by escape sequences). The Group always contains the
following parameters:
The remaining Parameters in each Group depend on the box type.
When JP2 information boxes are nested, the corresponding Parameter
Groups are also nested. JPEG2000 codestream (Contiguous_Codestream,
jp2c) boxes contain a Codestream Parameter Group that is defined by a
JPEG2000_Codestream_Info object.
N.B.: A {@link #WARNING_PARAMETER} will be placed at the end
of the Parameter set and further Source file scanning halted if the
previous JP2 box is invalid. The Value of the warning Parameter will
be a String describing the problem. Possible sources of warning
parameters are: The beginning of the Source file does not contain a
valid Signature box or the second box of the Source file is not a
valid File Type box.
@param skip_tiles true if tile segments are not to be included
in the Codestream Parameters; false otherwise.
@return This JP2_Info.
@throws IOException If there was a problem reading the Source file.
@see JPEG2000_Codestream_Info
*/
public JP2_Info Read
(
boolean skip_tiles
)
throws IOException
{
if (Image_Input_Stream == null)
return this;
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(">>> JP2_Info.Read");
Image_Input_Stream.mark ();
Stream_Position (0);
ByteOrder
byte_order = Image_Input_Stream.getByteOrder ();
if (byte_order != ByteOrder.BIG_ENDIAN)
Image_Input_Stream.setByteOrder (ByteOrder.BIG_ENDIAN);
// Remove any and all current parameters.
Remove_All ();
// Reset all image characterization values.
Reset_Image_Values ();
// Add the source file length.
long
length = -1;
try {length = Image_Input_Stream.length ();}
catch (IOException exception) {}
if (length >= 0)
{
try
{
Add (new Parameter (DATA_LENGTH_PARAMETER)
.Value (new Value (length).Units ("bytes"))
.Comments ("\nTotal source file length."));
}
catch (PVL_Exception exception) {}
}
boolean
tile_skipping = Skip_Tiles;
Skip_Tiles = skip_tiles;
try {Add_Boxes (this, 0);}
catch (IOException exception)
{
throw IO_Error
("Unable to Read JP2 Box information from the Source"
+ " at position " + Stream_Position,
exception);
}
catch (IllegalStateException exception)
{
try {Add (new Parameter (WARNING_PARAMETER)
.Value (exception.getMessage ()));}
catch (PVL_Exception except) {}
}
finally
{
Image_Input_Stream.setByteOrder (byte_order);
Skip_Tiles = tile_skipping;
try {Image_Input_Stream.reset ();}
catch (IOException exception)
{
throw IO_Error ("Could not reset the original Source position.",
exception);
}
}
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
("<<< JP2_Info.Read");
return this;
}
/** Test if the Source is a file in JP2 format.
If the {@link #JP2_Validity() JP2 Validity} value has already been
determined by {@link #Read(boolean) read}ing the Source file, then if
both the {@link #SIGNATURE_FOUND} and {@link #FILE_TYPE_FOUND}
validity flags have been set the file is in JP2 format. Otherwise an
attempt is made to read the first two JP2 boxes from the beginning of
the file which will provide the minimally necessary validity flags.
In this case the Source is repositioned back to its previous position
after the attempt to read the boxes. If no Source as been assigned
then the return value is false.
@return true if the beginning of the Source file contains a valid
signature box followed immediately by a valid file type box; false
otherwise.
*/
public boolean Is_JP2 ()
{
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
(">>> JP2_Info.Is_JP2");
boolean
is_JP2 = false;
if (Image_Input_Stream != null)
{
if (JP2_Validity == 0)
{
Image_Input_Stream.mark ();
ByteOrder
byte_order = Image_Input_Stream.getByteOrder ();
if (byte_order != ByteOrder.BIG_ENDIAN)
Image_Input_Stream.setByteOrder (ByteOrder.BIG_ENDIAN);
try
{
Image_Input_Stream.seek (0);
Stream_Position = 0;
// Signature.
Box_Parameter ();
// File Type.
Box_Parameter ();
}
catch (Exception exception) {}
finally
{
Image_Input_Stream.setByteOrder (byte_order);
try {Image_Input_Stream.reset ();}
catch (IOException exception) {}
}
}
is_JP2 = (JP2_Validity & (SIGNATURE_FOUND | FILE_TYPE_FOUND)) != 0;
}
if ((DEBUG & DEBUG_ACCESSORS) != 0)
System.out.println
("<<< JP2_Info.Is_JP2 : " + is_JP2);
return is_JP2;
}
/** Test if the Source file contains a complete JP2 format.
The Source must be {@link #Read(boolean) read} for this test to be valid.
@return true if the {@link #JP2_Validity() JP2 Validity} value has
all the {@link #JP2_COMPLETE} flags set; false otherwise.
*/
public boolean Is_Complete_JP2 ()
{return (JP2_Validity & JP2_COMPLETE) == JP2_COMPLETE;}
/** Get the current JP2 validity flags.
The bit flags in this value are updated as the Source file is
{@link #Read(boolean) read}:
@return The JP2 validity flags value.
*/
public int JP2_Validity ()
{return JP2_Validity;}
/** Get the number of bits per pixel for each component in the image.
@return An int array containing the number of bits per pixel for each
image component, as determined from the Image Header box. A
negative bits per pixel value signals that the pixel values are
signed; the number of bits per pixel is abs (value). The array
will be empty if the values are not yet known.
*/
public int[] Bits_per_Component ()
{return Bits_per_Component;}
//! Reset all image characterization class data members.
private void Reset_Image_Values ()
{
JP2_Validity = 0;
Image_Width =
Image_Height = -1;
Total_Components = -1;
Bits_per_Component = new int[0];
}
/*------------------------------------------------------------------------------
Codestream values
*/
/** Get the {@link JPEG2000_Codestream_Info#Codestream_Validity()} value.
@return The JPEG2000_Codestream_Info.Codestream_Validity value, or 0
if the value is not yet known.
*/
public int Codestream_Validity ()
{return (Codestream_Info == null) ? 0 : Codestream_Info.Codestream_Validity ();}
/** Get the number of components (bands) in the image.
If the value has not been obtained from the Image Header box the
value will be obtained from a {@link
JPEG2000_Codestream_Info#Total_Components() JPEG2000 codestream}
(Contiguous_Codestream, jp2c) box if available.
@return The number of image components, as determined from the Image
Header box. This will be -1 if the value is not yet known.
*/
public int Total_Components ()
{
if (Total_Components < 0 &&
Codestream_Info != null)
return Codestream_Info.Total_Components ();
return Total_Components;
}
/** Get the width of the image.
The image width is the distance on the reference grid from the
{@link JPEG2000_Codestream_Info#Horizontal_Image_Offset() horizontal
image offset} to the {@link
JPEG2000_Codestream_Info#Reference_Grid_Width() reference grid
width}. If the value has not been obtained from the Image Header box
the value will be obtained from a {@link
JPEG2000_Codestream_Info#Image_Width() JPEG2000 codestream}
(Contiguous_Codestream, jp2c) box if available.
N.B.: The image width is measured in terms of reference grid
columns. However, an individual image pixel may occupy more than one
reference grid column. The {@link
JPEG2000_Codestream_Info#Pixel_Width() pixel width} may be
different for each image component.
@return The reference grid width of the image. This will be -1 if the
value is not yet known.
*/
public long Image_Width ()
{
if (Image_Width < 0 &&
Codestream_Info != null)
return Codestream_Info.Image_Width ();
return Image_Width;
}
/** Get the height of the image.
The image height is the distance on the reference grid from the
{@link JPEG2000_Codestream_Info#Vertical_Image_Offset() vertical
image offset} to the {@link
JPEG2000_Codestream_Info#Reference_Grid_Height() reference grid
height}. If the value has not been obtained from the Image Header
box the value will be obtained from a {@link
JPEG2000_Codestream_Info#Image_Height() JPEG2000 codestream}
(Contiguous_Codestream, jp2c) box if available.
N.B.: The image height is measured in terms of reference grid
rows. However, an individual image pixel may occupy more than one
reference grid row. The {@link
JPEG2000_Codestream_Info#Pixel_Height() pixel height} may be
different for each image component.
@return The reference grid height of the image. This will be -1 if the
value is not yet known.
*/
public long Image_Height ()
{
if (Image_Height < 0 &&
Codestream_Info != null)
return Codestream_Info.Image_Height ();
return Image_Height;
}
/** Get the {@link JPEG2000_Codestream_Info#Reference_Grid_Width()} value.
@return The JPEG2000_Codestream_Info.Reference_Grid_Width value, or -1 if the
value is not yet known.
*/
public long Reference_Grid_Width ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Reference_Grid_Width ();}
/** Get the {@link JPEG2000_Codestream_Info#Reference_Grid_Height()} value.
@return The JPEG2000_Codestream_Info.Reference_Grid_Height value, or -1 if the
value is not yet known.
*/
public long Reference_Grid_Height ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Reference_Grid_Height ();}
/** Get the {@link JPEG2000_Codestream_Info#Horizontal_Image_Offset()} value.
@return The JPEG2000_Codestream_Info.Horizontal_Image_Offset value, or -1 if the
value is not yet known.
*/
public long Horizontal_Image_Offset ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Horizontal_Image_Offset ();}
/** Get the {@link JPEG2000_Codestream_Info#Vertical_Image_Offset()} value.
@return The JPEG2000_Codestream_Info.Vertical_Image_Offset value, or -1 if the
value is not yet known.
*/
public long Vertical_Image_Offset ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Vertical_Image_Offset ();}
/** Get the {@link JPEG2000_Codestream_Info#Pixel_Width()} value.
@return The JPEG2000_Codestream_Info.Pixel_Width value, or an empty
int array if the value is not yet known.
*/
public int[] Pixel_Width ()
{return (Codestream_Info == null) ? new int[0] : Codestream_Info.Pixel_Width ();}
/** Get the {@link JPEG2000_Codestream_Info#Pixel_Height()} value.
@return The JPEG2000_Codestream_Info.Pixel_Height value, or an empty
int array if the value is not yet known.
*/
public int[] Pixel_Height ()
{return (Codestream_Info == null) ? new int[0] : Codestream_Info.Pixel_Height ();}
/** Get the {@link JPEG2000_Codestream_Info#Tile_Width()} value.
@return The JPEG2000_Codestream_Info.Tile_Width value, or -1 if the
value is not yet known.
*/
public long Tile_Width ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Tile_Width ();}
/** Get the {@link JPEG2000_Codestream_Info#Tile_Height()} value.
@return The JPEG2000_Codestream_Info.Tile_Height value, or -1 if the
value is not yet known.
*/
public long Tile_Height ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Tile_Height ();}
/** Get the {@link JPEG2000_Codestream_Info#Horizontal_Tile_Offset()} value.
@return The JPEG2000_Codestream_Info.Horizontal_Tile_Offset value,
or -1 if the value is not yet known.
*/
public long Horizontal_Tile_Offset ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Horizontal_Tile_Offset ();}
/** Get the {@link JPEG2000_Codestream_Info#Vertical_Tile_Offset()} value.
@return The JPEG2000_Codestream_Info.Vertical_Tile_Offset value,
or -1 if the value is not yet known.
*/
public long Vertical_Tile_Offset ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Vertical_Tile_Offset ();}
/** Get the {@link JPEG2000_Codestream_Info#Total_Tiles()} value.
@return The JPEG2000_Codestream_Info.Total_Tiles value,
or -1 if the value is not yet known.
*/
public int Total_Tiles ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Total_Tiles ();}
/** Test if a {@link JPEG2000_Codestream_Info#Zero_Length_Tile_Part() zero
length tile-part} was found in the codestream.
@return true if a zero length tile-part was found; false otherwise.
*/
public boolean Zero_Length_Tile_Part ()
{return (Codestream_Info == null) ? false : Codestream_Info.Zero_Length_Tile_Part ();}
/** Get the {@link JPEG2000_Codestream_Info#Total_Quality_Layers()} value.
@return The JPEG2000_Codestream_Info.Total_Quality_Layers value, or -1 if
the value is not yet known.
*/
public int Total_Quality_Layers ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Total_Quality_Layers ();}
/** Get the {@link JPEG2000_Codestream_Info#Progression_Order()} value.
@return The JPEG2000_Codestream_Info.Progression_Order value, or -1
if the value is not yet known.
*/
public int Progression_Order ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Progression_Order ();}
/** Get the {@link JPEG2000_Codestream_Info#Total_Resolution_Levels()} value.
@return The JPEG2000_Codestream_Info.Total_Resolution_Levels value, or -1 if
the value is not yet known.
*/
public int Total_Resolution_Levels ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Total_Resolution_Levels ();}
/** Get the {@link JPEG2000_Codestream_Info#Transform()} value.
@return The JPEG2000_Codestream_Info.Transform value, or -1 if the
value is not yet known.
*/
public int Transform ()
{return (Codestream_Info == null) ? -1 : Codestream_Info.Transform ();}
/*==============================================================================
Box Parameters
*/
/** Assemble a Parameter Aggregate describing a JP2 box from a byte array.
A single JP2 box is parsed from the byte data. If the data contains
additional JP2 box contents they are ignored. {@link
JPEG2000_Info#Use_Data_Position(boolean) Including data position}
parameters is disabled as is {@link
JPEG2000_Info#Throw_Illegal_State(boolean) illegal box organizaion
detection}.
@param data A byte array.
@param offset The offset where the JP2 box is expected to start.
@param length The maximum amount of byte data to be read. However,
if the data array ends before length bytes after the starting
offset, then only the available bytes will be read.
@return A Parameter Aggregate containing Parameters describing the
JP2 box contents. This will be null if the contents of a recognized
box were not available within the data length.
*/
public static Parameter Box
(
byte[] data,
int offset,
int length
)
{
if (data == null)
return null;
JP2_Info
info = new JP2_Info ();
info.Source (new MemoryCacheImageInputStream (new ByteArrayInputStream
(data, offset, length)));
info.Source ().setByteOrder (ByteOrder.BIG_ENDIAN);
info.Use_Data_Position (false);
info.Throw_Illegal_State (false);
Parameter
box = null;
try {box = info.Box_Parameter ();}
catch (Exception exception) {}
return box;
}
/** Assemble a Parameter Aggregate from a byte array of JP2 box data.
@param data A byte array.
@return A Parameter Aggregate containing Parameters describing the
JP2 box contents. This will be null if the contents of a recognized
box were not available within the data array.
@see #Box(byte[], int, int)
*/
public static Parameter Box
(
byte[] data
)
{return Box (data, 0, data.length);}
private void Add_Boxes
(
Parameter container,
long end_position
)
throws IOException, IllegalStateException
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(">>> JP2_Info.Add_Boxes: To " + container.Name () + '\n'
+" From stream position " + Stream_Position + '\n'
+" Until stream position " + end_position);
Parameter
box = null;
if (end_position == 0)
end_position = Long.MAX_VALUE;
try
{
while (Stream_Position < end_position &&
(box = Box_Parameter ()) != null)
{
try {container.Add (box);}
catch (PVL_Exception exception) {}
}
}
catch (EOFException exception)
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" JP2_Info.Add_Boxes: EOF at Stream_Postion "
+ Stream_Position);
}
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
("<<< JP2_Info.Add_Boxes");
}
private Parameter Box_Parameter ()
throws IOException, IllegalStateException
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(">>> JP2_Info.Box_Parameter");
long
box_position = Stream_Position,
box_length = Read_Unsigned_int (LENGTH_PARAMETER);
int
type_code = Read_int (TYPE_PARAMETER);
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" JP2_Info.Box_Parameter: \"" + int_to_String (type_code)
+ "\" (0x" + Integer.toHexString (type_code)
+ ") - " + Box_Name (type_code) + '\n'
+" Position = " + box_position + '\n'
+" Length = " + box_length);
if (box_length == 0)
{
try
{
long
stream_length = Image_Input_Stream.length ();
box_length = stream_length - box_position;
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" Stream length = " + stream_length + '\n'
+" Remaining length = " + box_length);
}
catch (IOException exception) {}
}
else if (box_length == 1)
{
box_length = Read_long ("box long length");
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" Long length = " + box_length);
}
Parameter
box = new Parameter (int_to_String (type_code));
try
{
box
.Add (new Parameter (NAME_PARAMETER)
.Value (Box_Name (type_code)))
.Add (new Parameter (TYPE_PARAMETER)
.Value (new Value (type_code).Base (16)));
if (Use_Data_Position)
box
.Add (new Parameter (POSITION_PARAMETER)
.Value (new Value (box_position).Units ("byte offset")));
box
.Add (new Parameter (LENGTH_PARAMETER)
.Value (new Value (box_length).Units ("bytes")));
}
catch (PVL_Exception exception) {}
if (JP2_Validity == 0)
{
// The first box must be the Signature.
if (type_code != SIGNATURE_TYPE ||
box_length != 12)
{
if (Throw_Illegal_State)
throw new IllegalStateException (ID + '\n'
+ "Not a valid JP2 file: No initial signature box.");
}
else
JP2_Validity = SIGNATURE_FOUND;
}
else if (JP2_Validity == SIGNATURE_FOUND)
{
// The second box must be the File Type.
if (type_code != FILE_TYPE)
{
if (Throw_Illegal_State)
throw new IllegalStateException (ID + '\n'
+ "Not a valid JP2 file: Missing File Type box.");
}
else
JP2_Validity |= FILE_TYPE_FOUND;
}
long
end_position = box_position + box_length;
switch (type_code)
{
// Super boxes that contain additional boxes.
case HEADER_TYPE:
JP2_Validity |= JP2_HEADER_FOUND;
case RESOLUTION_TYPE:
case UUID_INFO_TYPE:
case ASSOCIATION_TYPE:
Add_Boxes (box, end_position);
break;
// Basic boxes.
case SIGNATURE_TYPE:
Signature_Parameters (box);
break;
case FILE_TYPE:
File_Type_Parameters (box, end_position);
break;
case IMAGE_HEADER_TYPE:
JP2_Validity |= IMAGE_HEADER_FOUND;
Image_Header_Parameters (box);
break;
case BITS_PER_COMPONENT_TYPE:
Bits_per_Component_Parameters (box, end_position);
break;
case COLOUR_SPECIFICATION_TYPE:
JP2_Validity |= COLOUR_SPECIFICATION_FOUND;
Colour_Specification_Parameters (box, end_position);
break;
case PALETTE_TYPE:
Palette_Parameters (box, end_position);
break;
case COMPONENT_MAPPING_TYPE:
Component_Mapping_Parameters (box, end_position);
break;
case CHANNEL_DEFINITION_TYPE:
Channel_Definition_Parameters (box);
break;
case CAPTURE_RESOLUTION_TYPE:
case DEFAULT_DISPLAY_RESOLUTION_TYPE:
Resolution_Parameters (box);
break;
case UUID_TYPE:
UUID_Parameters (box, end_position);
break;
case UUID_LIST_TYPE:
UUID_List_Parameters (box);
break;
case URL_TYPE:
URL_Parameters (box, end_position);
break;
case LABEL_TYPE:
case XML_TYPE:
Text_Parameter (box, end_position);
break;
// JPEG2000 codestream box.
case CONTIGUOUS_CODESTREAM_TYPE:
JP2_Validity |= CONTIGUOUS_CODESTREAM_FOUND;
Contiguous_Codestream_Parameters (box, end_position);
break;
// JPIP placeholder box.
case PLACEHOLDER_TYPE:
Placeholder_Parameters (box, end_position);
break;
// Opaque boxes.
case INTELLECTUAL_PROPERTY_TYPE:
default:
if (Use_Data_Position)
Data_Position_Parameters (box, end_position);
else
Data_Offset_Parameters (box, 0, end_position - Stream_Position);
}
if (Stream_Position < end_position)
Stream_Position (end_position);
else
if (Throw_Illegal_State &&
Stream_Position > end_position)
throw new IllegalStateException (ID + '\n'
+ "Invalid " + box.Name () + " contents -\n"
+ " expected length " + box_length
+ " but used length " + (Stream_Position - box_position));
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(((box == null) ? "" : box.Description ()) + '\n'
+"<<< JP2_Info.Box_Parameter: " + box);
return box;
}
private void Signature_Parameters
(
Parameter box
)
throws IOException, IllegalStateException
{
try {
int
signature = Read_int (SIGNATURE_PARAMETER);
box.Add (new Parameter (SIGNATURE_PARAMETER)
.Value (new Value (signature).Base (16)));
if (Throw_Illegal_State &&
signature != SIGNATURE)
throw new IllegalStateException (ID + '\n'
+ "Invalid Signature: Expected " + SIGNATURE + ", found " + signature);
}
catch (PVL_Exception exception) {}
}
private void File_Type_Parameters
(
Parameter box,
long end_position
)
throws IOException, IllegalStateException
{
try {
boolean
JP2_compatible = false;
String
compatibility;
int
datum = Read_int (BRAND_PARAMETER);
compatibility = int_to_String (datum);
if (compatibility.equals (JP2_COMPATIBLE))
JP2_compatible = true;
box.Add (new Parameter (BRAND_PARAMETER)
.Value (compatibility));
box.Add (new Parameter (MINOR_VERSION_PARAMETER)
.Value (Read_Unsigned_int (MINOR_VERSION_PARAMETER)));
Value
list = new Value ().Type (Value.SET);
while (Stream_Position < end_position)
{
datum = Read_int (COMPATIBILITY_LIST_PARAMETER);
compatibility = int_to_String (datum);
if (compatibility.equals (JP2_COMPATIBLE))
JP2_compatible = true;
list.Add (new Value (compatibility));
}
box.Add (new Parameter (COMPATIBILITY_LIST_PARAMETER)
.Value (list));
if (Throw_Illegal_State &&
! JP2_compatible)
throw new IllegalStateException (ID + '\n'
+ "File Type Compatibility \"" + JP2_COMPATIBLE + "\" not found.");
}
catch (PVL_Exception exception) {}
}
private void Image_Header_Parameters
(
Parameter box
)
throws IOException
{
try {
Parameter
value_bits;
box
.Add (new Parameter (HEIGHT_PARAMETER)
.Value (new Value (Image_Height =
Read_Unsigned_int (HEIGHT_PARAMETER)).Units ("rows")))
.Add (new Parameter (WIDTH_PARAMETER)
.Value (new Value (Image_Width =
Read_Unsigned_int (WIDTH_PARAMETER)).Units ("columns")))
.Add (new Parameter (TOTAL_COMPONENTS_PARAMETER)
.Value (Total_Components =
Read_Unsigned_short (TOTAL_COMPONENTS_PARAMETER)))
.Add (value_bits = Value_Bits_Parameter (box.Name (), Stream_Position + 1))
.Add (new Parameter (COMPRESSION_TYPE_PARAMETER)
.Value (Read_Unsigned_byte (COMPRESSION_TYPE_PARAMETER)))
.Add (new Parameter (COLORSPACE_UNKNOWN_PARAMETER)
.Value ((Read_Unsigned_byte (COLORSPACE_UNKNOWN_PARAMETER) != 0) ?
"true" : "false"))
.Add (new Parameter (INTELLECTUAL_PROPERTY_PARAMETER)
.Value ((Read_Unsigned_byte (INTELLECTUAL_PROPERTY_PARAMETER) != 0) ?
"true" : "false"));
Bits_per_Component = int_Array (value_bits);
}
catch (PVL_Exception exception) {}
}
private void Bits_per_Component_Parameters
(
Parameter box,
long end_position
)
throws IOException
{
try {
Parameter
value_bits;
box.Add (value_bits = Value_Bits_Parameter (box.Name (), end_position));
// The values from this box overrides the values from the Image Header box.
Bits_per_Component = int_Array (value_bits);
}
catch (PVL_Exception exception) {}
}
private void Colour_Specification_Parameters
(
Parameter box,
long end_position
)
throws IOException
{
try {
long
start_position = Stream_Position;
int
method = Read_Unsigned_byte (SPECIFICATION_METHOD_PARAMETER);
box
.Add (new Parameter (SPECIFICATION_METHOD_PARAMETER)
.Value (method))
.Add (new Parameter (PRECEDENCE_PARAMETER)
.Value (Read_Unsigned_byte (PRECEDENCE_PARAMETER)))
.Add (new Parameter (COLOURSPACE_APPROXIMATION_PARAMETER)
.Value (Read_Unsigned_byte (COLOURSPACE_APPROXIMATION_PARAMETER)));
if (method == ENUMERATED_COLOURSPACE)
box.Add (new Parameter (ENUMERATED_COLOURSPACE_PARAMETER)
.Value (Read_Unsigned_int (ENUMERATED_COLOURSPACE_PARAMETER)));
else
{
if (Use_Data_Position)
Data_Position_Parameters (box, end_position);
else
Data_Offset_Parameters (box,
Stream_Position - start_position, end_position - start_position);
}
}
catch (PVL_Exception exception) {}
}
private void Palette_Parameters
(
Parameter box,
long end_position
)
throws IOException
{
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(">>> JP2_Info.Palette_Parameters:\n"
+" From stream position " + Stream_Position + '\n'
+" Until stream position " + end_position);
try {
int
entries = Read_Unsigned_short (box.Name () + ' ' + ENTRIES_PARAMETER),
columns = Read_Unsigned_byte (COLUMNS_PARAMETER);
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" entries = " + entries + '\n'
+" columns = " + columns);
box.Add (new Parameter (ENTRIES_PARAMETER)
.Value (entries));
box.Add (new Parameter (COLUMNS_PARAMETER)
.Value (columns));
Parameter
value_bits =
Value_Bits_Parameter (box.Name (), Stream_Position + columns);
box.Add (value_bits);
int[]
bits_per_column = int_Array (value_bits);
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
(" bits_per_column = " + bits_per_column);
Value
palette = new Value ().Type (Value.SEQUENCE),
palette_row;
while (entries-- != 0)
{
palette_row = new Value ().Type (Value.SEQUENCE);
for (int column = 0;
column < columns;
++column)
palette_row.Add (new Value
(Read_Value (box.Name () + ' ' + VALUES_PARAMETER,
bits_per_column[column])));
palette.Add (palette_row);
}
box.Add (new Parameter (VALUES_PARAMETER)
.Value (palette));
}
catch (PVL_Exception exception) {}
if ((DEBUG & DEBUG_PARAMETERS) != 0)
System.out.println
("<<< JP2_Info.Palette_Parameters");
}
private void Component_Mapping_Parameters
(
Parameter box,
long end_position
)
throws IOException
{
try {
String
description = box.Name () + ' ' + MAP_PARAMETER;
Value
map = new Value ().Type (Value.SEQUENCE),
set;
while (Stream_Position < end_position)
{
set = new Value ().Type (Value.SEQUENCE)
.Add (new Value (Read_Unsigned_short (description +
" component index")))
.Add (new Value (Read_Unsigned_byte (description +
" map type")))
.Add (new Value (Read_Unsigned_byte (description +
" palette index")));
map.Add (set);
}
box.Add (new Parameter (MAP_PARAMETER)
.Comments ("\nMap entries:\n" +
" Component index,\n" +
" Map type,\n" +
" Palette index")
.Value (map));
}
catch (PVL_Exception exception) {}
}
private void Channel_Definition_Parameters
(
Parameter box
)
throws IOException
{
try {
int
entries = Read_Unsigned_short (box.Name () + ' ' + ENTRIES_PARAMETER);
box.Add (new Parameter (ENTRIES_PARAMETER)
.Value (entries));
String
description = box.Name () + ' ' + MAP_PARAMETER;
Value
map = new Value ().Type (Value.SEQUENCE),
set;
while (entries-- != 0)
{
set = new Value ().Type (Value.SEQUENCE)
.Add (new Value (Read_Unsigned_short (description +
" channel index")))
.Add (new Value (Read_Unsigned_short (description +
" channel type")))
.Add (new Value (Read_Unsigned_short (description +
" channel association")));
map.Add (set);
}
box.Add (new Parameter (MAP_PARAMETER)
.Comments ("\nChannel definition entries:\n" +
" Channel index,\n" +
" Channel type,\n" +
" Channel association")
.Value (map));
}
catch (PVL_Exception exception) {}
}
private void Resolution_Parameters
(
Parameter box
)
throws IOException
{
try {
box
.Add (new Parameter (VERTICAL_NUMERATOR_PARAMETER)
.Value (Read_Unsigned_short (VERTICAL_NUMERATOR_PARAMETER)))
.Add (new Parameter (VERTICAL_DENOMINATOR_PARAMETER)
.Value (Read_Unsigned_short (VERTICAL_DENOMINATOR_PARAMETER)));
int
numerator = Read_Unsigned_short (HORIZONTAL_NUMERATOR_PARAMETER),
denominator = Read_Unsigned_short (HORIZONTAL_DENOMINATOR_PARAMETER);
box
.Add (new Parameter (VERTICAL_EXPONENT_PARAMETER)
.Value (Read_byte (VERTICAL_EXPONENT_PARAMETER)))
.Add (new Parameter (HORIZONTAL_NUMERATOR_PARAMETER)
.Value (numerator))
.Add (new Parameter (HORIZONTAL_DENOMINATOR_PARAMETER)
.Value (denominator))
.Add (new Parameter (HORIZONTAL_EXPONENT_PARAMETER)
.Value (Read_byte (HORIZONTAL_EXPONENT_PARAMETER)));
}
catch (PVL_Exception exception) {}
}
private void UUID_Parameters
(
Parameter box,
long end_position
)
throws IOException
{
try {
long
start_position = Stream_Position;
box.Add (UUID_Parameter (box.Name ()));
if (Use_Data_Position)
Data_Position_Parameters (box, end_position);
else
Data_Offset_Parameters (box,
Stream_Position - start_position, end_position - start_position);
}
catch (PVL_Exception exception) {}
}
private void UUID_List_Parameters
(
Parameter box
)
throws IOException
{
try {
int
entries = Read_Unsigned_short (box.Name () + ' ' + ENTRIES_PARAMETER);
box.Add (new Parameter (ENTRIES_PARAMETER)
.Value (entries));
while (entries-- != 0)
box.Add (UUID_Parameter (box.Name ()));
}
catch (PVL_Exception exception) {}
}
private Parameter UUID_Parameter
(
String description
)
throws IOException
{
String
describe = description + ' ' + UUID_PARAMETER;
Parameter
parameter = new Parameter (UUID_PARAMETER);
try {
Value
uuid = new Value ().Type (Value.SEQUENCE);
for (int index = 0;
index < NUMBER_OF_UUID_VALUES;
++index)
uuid.Add (new Value (Read_Unsigned_byte (describe)).Base (16));
parameter.Value (uuid);
}
catch (PVL_Exception exception) {}
return parameter;
}
private void URL_Parameters
(
Parameter box,
long end_position
)
throws IOException
{
try {
box
.Add (new Parameter (VERSION_PARAMETER)
.Value (Read_Unsigned_byte (box.Name () + ' ' + VERSION_PARAMETER)))
.Add (new Parameter (FLAGS_PARAMETER)
.Value (new Value
(Read_Value (box.Name () + ' ' + FLAGS_PARAMETER, 24))
.Base (16)))
.Add (new Parameter (URL_PARAMETER)
.Value (Read_String (box.Name (), end_position)));
}
catch (PVL_Exception exception) {}
}
private void Text_Parameter
(
Parameter box,
long end_position
)
throws IOException
{
try {
box
.Add (new Parameter (TEXT_PARAMETER)
.Value (new Value
(Read_String (box.Name (), end_position))
.Type (Value.TEXT)));
}
catch (PVL_Exception exception) {}
}
private void Contiguous_Codestream_Parameters
(
Parameter box,
long end_position
)
throws IOException
{
if (Use_Data_Position)
Data_Position_Parameters (box, end_position);
else
Data_Offset_Parameters (box,
0, end_position - Stream_Position);
try {
JPEG2000_Codestream_Info
codestream_info = new JPEG2000_Codestream_Info
(Image_Input_Stream, end_position, Skip_Tiles);
codestream_info.Name (CODESTREAM_PARAMETER);
box.Add (codestream_info);
if (Codestream_Info == null)
Codestream_Info = codestream_info;
}
catch (PVL_Exception exception) {}
}
private void Placeholder_Parameters
(
Parameter box,
long end_position
)
throws IOException
{
try {
long
start_position = Stream_Position;
int
flags = Read_int (box.Name () + ' ' + FLAGS_PARAMETER);
box
.Add (new Parameter (FLAGS_PARAMETER)
.Value (new Value (flags).Base (16))
.Comments ("\n"
+ (((flags & PLACEHOLDER_FLAGS_ORIGINAL_MASK) == 0) ?
"No o" : "O") + "riginal box provided.\n"
+ (((flags & PLACEHOLDER_FLAGS_EQUIVALENT_MASK) == 0) ?
"No e" : "E") + "quivalent box provided.\n"
+ (((flags & PLACEHOLDER_FLAGS_CODESTREAM_MASK) == 0) ?
"No c" : "C") + "odestream provided."));
Parameter
group;
if ((flags & PLACEHOLDER_FLAGS_ORIGINAL_MASK) != 0)
{
group = new Parameter (ORIGINAL_BOX_PARAMETER);
group.Add (new Parameter (BIN_ID_PARAMETER)
.Value (Read_long (box.Name ()
+ ' ' + ORIGINAL_BOX_PARAMETER + ' ' + BIN_ID_PARAMETER)));
Box_Header_Parameters (group);
box.Add (group);
}
if ((flags & PLACEHOLDER_FLAGS_EQUIVALENT_MASK) != 0)
{
group = new Parameter (EQUIVALENT_BOX_PARAMETER);
group.Add (new Parameter (BIN_ID_PARAMETER)
.Value (Read_long (box.Name ()
+ ' ' + EQUIVALENT_BOX_PARAMETER + ' ' + BIN_ID_PARAMETER)));
Box_Header_Parameters (group);
box.Add (group);
}
if ((flags & PLACEHOLDER_FLAGS_CODESTREAM_MASK) != 0)
{
box.Add (new Parameter (CODESTREAM_ID_PARAMETER)
.Value (Read_long (box.Name () + ' ' + CODESTREAM_ID_PARAMETER)));
long
total = Read_Unsigned_int (box.Name () + ' ' +
TOTAL_CODESTREAMS_PARAMETER);
if ((flags & PLACEHOLDER_FLAGS_MULTIPLE_CODESTREAM_MASK) == 0)
total = 1;
box.Add (new Parameter (TOTAL_CODESTREAMS_PARAMETER)
.Value (total));
}
if (Stream_Position != end_position)
{
group = new Parameter (EXTENDED_BOX_LIST_PARAMETER);
if (Use_Data_Position)
Data_Position_Parameters (group, end_position);
else
Data_Offset_Parameters (group,
Stream_Position - start_position, end_position - start_position);
box.Add (group);
}
}
catch (PVL_Exception exception) {}
}
private void Box_Header_Parameters
(
Parameter box
)
throws IOException
{
try {
long
box_length = Read_Unsigned_int (box.Name () + ' ' + LENGTH_PARAMETER);
int
type_code = Read_int (box.Name () + ' ' + TYPE_PARAMETER);
if (box_length == 1)
box_length = Read_long (box.Name () + " box long length");
box
.Add (new Parameter (NAME_PARAMETER)
.Value (Box_Name (type_code)))
.Add (new Parameter (TYPE_PARAMETER)
.Value (new Value (type_code).Base (16)))
.Add (new Parameter (LENGTH_PARAMETER)
.Value (new Value (box_length).Units ("bytes")));
}
catch (PVL_Exception exception) {}
}
/*==============================================================================
Helpers
*/
/** Get the descriptive box name for a box type.
@param type_code The box type code value. This may be obtained
from the {@link #TYPE_PARAMETER} present in each box Parameter
Group.
@return The box name String as used in the {@link #NAME_PARAMETER}
of each box Parameter Group.
*/
public static String Box_Name
(
int type_code
)
{
String
string = (String)Box_Names.get (new Integer (type_code));
if (string == null)
string = UNKNOWN;
return string;
}
/** Convert an int value to a String.
Each byte, starting with the most significant byte, of the value
is appended as a character to a String. Non-printable characters
are expanded to escape sequences.
@param value The int value to be converted.
@return The String repesentation of the value.
*/
public static String int_to_String
(
int value
)
{
String_Buffer
string = new String_Buffer ();
int
shift = 24,
mask = 0x7F000000;
for (shift = 24;
shift >= 0;
shift -= 8,
mask >>= 8)
string.append ((char)((value & mask) >> shift));
// Escape any non-printable characters.
string.special_to_escape ();
return string.toString ();
}
/** Generate an IOException containing a message.
If the provided message does not already contain the class {@link
#ID} the ID and a NL character is prepended to the message (or the ID
becomes the message if it is null). If a non-null exception is
provided, the message from the exception is appended, after a NL
character, to the message used in constructing the IOException.
If the exception argument is an instance of EOFException the returned
IOException will also be an EOFException. If the exception argument
is non-null and contains a cause, an attempt is made to apply the
cause to the new IOException (failure to apply the cause is ignored).
@param message The message String to be included in the IOException.
@return An IOException.
@see #IOException(String, Exception)
*/
private IOException IO_Error
(
String message,
Exception exception
)
{
if (message == null)
message = ID;
else if (message.indexOf (ID) < 0)
message = ID + '\n' + message;
if (exception != null)
message += "\n" + exception.getMessage ();
IOException
except;
if (exception instanceof EOFException)
except = new EOFException (message);
else
except = new IOException (message);
if (exception != null)
{
Throwable
cause = exception.getCause ();
if (cause != null)
{
try {except.initCause (cause);}
catch (IllegalStateException e) {}
}
}
return except;
}
/** Generate an IOException containing a message.
@param message The message String to be included in the IOException.
@return An IOException.
@see #IOException(String, Exception)
*/
private IOException IO_Error
(
String message
)
{return IO_Error (message, null);}
/*==============================================================================
Main
*/
//! Exit status values.
public static final int
SUCCESS = 0,
SYNTAX_ERROR = 1,
IO_EXCEPTION = 2,
NO_INFO = 3,
PVL_ERROR = 4,
INVALID_FILE = 5;
/** Report the JP2_Info found in a file.
@param arguments The arguments String array.
@see #Usage()
*/
public static void main
(
String[] arguments
)
{
if ((DEBUG & DEBUG_MAIN) != 0)
System.out.println
("*** " + ID);
boolean
skip_tiles = true,
EOC_search = false,
GUI = false;
String
source = null;
Vector
names = new Vector (),
patterns = new Vector ();
int
exit_status = SUCCESS;
for (int argument = 0;
argument < arguments.length;
++argument)
{
if (arguments[argument].startsWith ("-") &&
arguments[argument].length () > 1)
{
switch (arguments[argument].charAt (1))
{
case 'N':
case 'n':
int
index = arguments[argument].indexOf ('_');
if (index < 0)
{
System.out.println
("Unknown option: " + arguments[argument]);
Usage ();
}
switch (arguments[argument].charAt (++index))
{
case 'T':
case 't':
skip_tiles = true;
break;
case 'E':
case 'e':
EOC_search = false;
break;
default:
System.out.println
("Unknown option: " + arguments[argument]);
}
break;
case 'T':
case 't':
skip_tiles = false;
break;
case 'E':
case 'e':
EOC_search = true;
break;
case 'F':
case 'f':
if (++argument == arguments.length)
Usage ();
names.add (arguments[argument]);
break;
case 'P':
case 'p':
if (++argument == arguments.length)
Usage ();
patterns.add (arguments[argument]);
break;
case 'G':
case 'g':
GUI = true;
break;
default:
System.out.println
("Unknown option: " + arguments[argument]);
case 'H':
case 'h':
Usage ();
}
}
else if (source == null)
source = arguments[argument];
else
{
System.err.println ("Only one source, please.");
Usage ();
}
}
if (source == null)
{
System.err.println ("A source must be specified.");
Usage ();
}
// Get the Info.
JP2_Info
info = null;
JPEG2000_Codestream_Info.EOC_Search = EOC_search;
try {info = new JP2_Info (source, skip_tiles);}
catch (Exception exception)
{
System.out.println (exception.getMessage ());
System.exit (IO_EXCEPTION);
}
// Report the Info.
if (info == null)
{
System.out.println ("No JP2 Info");
System.exit (NO_INFO);
}
int
validity;
if (! info.Is_Complete_JP2 ())
{
System.out.println ("\n>>> WARNING <<< Incomplete JP2 file contents!\n");
validity = info.JP2_Validity ();
if ((validity & SIGNATURE_FOUND) == 0)
System.out.println (" Signature box not found.");
if ((validity & FILE_TYPE_FOUND) == 0)
System.out.println (" File Type box not found.");
if ((validity & JP2_HEADER_FOUND) == 0)
System.out.println (" JP2 Header box not found.");
if ((validity & IMAGE_HEADER_FOUND) == 0)
System.out.println (" Image Header box not found.");
if ((validity & COLOUR_SPECIFICATION_FOUND) == 0)
System.out.println (" Colour Specification box not found.");
if ((validity & CONTIGUOUS_CODESTREAM_FOUND) == 0)
System.out.println (" JPEG2000 Contiguous Codestream box not found.");
System.out.println ();
exit_status = INVALID_FILE;
}
validity = info.Codestream_Validity ();
boolean
EOC_missing =
((! info.Skip_Tiles ()) &&
((validity & JPEG2000_Codestream_Info.EOC_FOUND) == 0)) ||
(info.Zero_Length_Tile_Part () &&
JPEG2000_Codestream_Info.EOC_Search);
if ((validity != 0 &&
(validity != JPEG2000_Codestream_Info.CODESTREAM_COMPLETE)) ||
EOC_missing)
{
if (info.Is_Complete_JP2 ())
System.out.println ();
System.out.println (">>> WARNING <<< Incomplete JPEG2000 codestream.\n");
if ((validity & JPEG2000_Codestream_Info.SOC_FOUND) == 0)
System.out.println (" Start of Codestream marker not found.");
if ((validity & JPEG2000_Codestream_Info.SIZ_FOUND) == 0)
System.out.println (" Size marker not found.");
if ((validity & JPEG2000_Codestream_Info.COD_FOUND) == 0)
System.out.println (" Coding Style Default marker not found.");
if ((validity & JPEG2000_Codestream_Info.QCD_FOUND) == 0)
System.out.println (" Quantization Default marker not found.");
if (EOC_missing)
System.out.println (" End of Codestream marker not found.");
System.out.println ();
exit_status = INVALID_FILE;
}
if (! names.isEmpty () ||
! patterns.isEmpty ())
{
Parameter
select = new Parameter (),
parameter;
Selector
criteria;
String
name;
int
root_name_length = info.Name ().length () + 1;
Iterator
list;
if (! names.isEmpty ())
{
criteria = new Selection ().Name (true).Specific (false);
list = names.iterator ();
while (list.hasNext ())
{
select.Name ((String)list.next ());
parameter = null;
while ((parameter = info.Find (select, criteria, parameter))
!= null)
{
name = parameter.Name ();
parameter.Name (parameter.Path_to_Name ()
.substring (root_name_length) + name);
try {parameter.Write ();}
catch (Exception exception)
{
System.out.println
("PVL error -\n" + exception.getMessage () + "\n");
System.exit (PVL_ERROR);
}
parameter.Name (name);
}
}
}
if (! patterns.isEmpty ())
{
criteria = new Selection ().Name (true).Pattern_Match (true);
list = patterns.iterator ();
while (list.hasNext ())
{
select.Name ((String)list.next ());
parameter = null;
while ((parameter = info.Find (select, criteria, parameter))
!= null)
{
name = parameter.Name ();
parameter.Name (parameter.Path_to_Name ()
.substring (root_name_length) + name);
try {parameter.Write ();}
catch (Exception exception)
{
System.out.println
("PVL error -\n" + exception.getMessage () + "\n");
System.exit (PVL_ERROR);
}
parameter.Name (name);
}
}
}
}
else if (GUI)
{
Parameter_View
view = new Parameter_View (info);
view.setVisible (true);
}
else
{
System.out.println (String_Buffer.escape_to_special (info.Description ()));
System.exit (exit_status);
}
}
/** Print the command line usage syntax.
JP2_Info
[-[No_]Tiles]
[-Gui]
[-Find <parameter>]
[-Pattern <regex>]
<source>
The contents of the specified file are scanned for JP2 file format
boxes and JPEG2000 codestream segments. The information found is
reported in the form of PVL parameters containing all the data
element values.
0 - Success
N.B.This method always results in a System.exit with a status
of 1.
*/
public static void Usage ()
{
System.out.println
(
ID + '\n' +
"Usage: JP2_Info [
The URL used to reference the source file must use the http protocol.
Any HTTP server compatible with version 1.1 of the protocol should
be capable of providing selective access to the source file.
The source file data is buffered using a sliding window that is
mapped to an arbitrary location offset of the source file. Data is
fetched on demand using a Content_Range request to the server from
which the response data content is placed at the appropriate position
in the buffer. During normal read operations when the end of buffered
data is reached a relatively small input increment is fetched into
the buffer. When the amount of data has reached the buffer capacity
the buffer "slides" forward, dropping data from the beginning of the
buffer Arbitrary random access seeks within the source file are
supported. If the seek location is currently buffered, no data fetch
is needed, of course. Seeks beyond the range of buffered data to a
"nearby" location will retain as much buffered data as possible to
optimize short seeks.
If the connection to the server is lost repeated attempts are made
to reconnect. Reconnecting to the server does cause any loss of
buffered data.
@author Bradford Castalia UA/PIRL
@version 1.14
@see javax.imageio.stream.ImageInputStream
*/
public class HTTP_ImageInputStream
extends ImageInputStreamImpl
{
public static final String
ID = "PIRL.Image_Tools.HTTP_ImageInputStream (1.14 2012/04/16 06:10:20)";
//------------------------------------------------------------------------------
// Data source
/** The HTTP version identifier used in communication with the server.
*/
public static final String
HTTP_VERSION = "HTTP/1.1";
/** The character encoding for messages sent to the server.
*/
public static final String
ENCODING_SCHEME = "UTF-8";
/** The default {@link #User_Agent(String) User Agent} reported to the server.
*/
public static final String
DEFAULT_USER_AGENT = "HTTP_ImageInputStream 1.14 2012/04/16 06:10:20";
/** The default port to use for communication with the server.
The URL used to construct the HTTP_ImageInputStream may specify
a different port to be used.
*/
public static final int
DEFAULT_PORT = 80;
/** The amount of time (ms) to wait for a server connection.
*/
public static final int
DEFAULT_CONNECT_TIMEOUT = 5000;
/** The amount of time (ms) to wait before trying to reconnect with the server.
*/
public static final long
RECONNECT_WAIT = 3000;
/** The maximum number of repeated server reconnect tries.
*/
public static final int
MAX_RECONNECT_ATTEMPTS = 5;
/** HTTP {@link #Status() Status} code when the source can not be found
on the server.
*/
public static final int
SOURCE_NOT_FOUND_STATUS = 404;
/** HTTP {@link #Status() Status} code value below which the request
is deemed successful.
*/
public static final int
SUCCESS_STATUS_LIMIT = 300;
private URL
Source_URL = null;
private static String
Default_User_Agent = DEFAULT_USER_AGENT;
private String
User_Agent = Default_User_Agent,
Server_Hostname = null,
Source_Pathname = null;
private InetSocketAddress
Server_Address = null;
private Socket
Server_Socket = null;
private BufferedWriter
Server_Writer = null;
private static final int
HEADERS_BUFFER_SIZE = 512;
private InputStream
Server_Input = null;
/** Source size value if no source has been found.
*/
protected long
NO_SOURCE_SIZE = Long.MAX_VALUE;
/** Total size (bytes) of the source data file.
The value is initialized to {@link #NO_SOURCE_SIZE} to indicate that
the size is unknown. When HTTP response {@link #Headers() headers}
are received an attempt is made to get the {@link #Source_Size()
size of the source file} if it is not already known.
*/
protected long
Source_Size = NO_SOURCE_SIZE; // Get the size from the server.
/* !!! Workaround !!!
The reset mehod of ImageInputStreamImpl throws an exception if the
position popped from the markByteStack is located before the
flushedPos (beginning of the buffer). This implementation allows
seeking to a location before the beginning of the buffer. The
workaround is to leave the flushedPos at zero and use an alternate
variable for the buffer stream location.
*/
private long
Buffer_Location = 0;
//! Total number of bytes transmitted to/from the sever.
private long
Total_Sent = 0,
Total_Received = 0;
//------------------------------------------------------------------------------
// HTTP headers
private Vector
HTTP_Headers = new Vector ();
private int
HTTP_Status = 0;
private boolean
Logging = false;
/** When {@link #Logging(boolean) Logging} is enabled, the prefix to
print before each request message line that is reported sent to the
server.
*/
public static final String
LOG_OUTPUT_PREFIX = "<< ";
/** When {@link #Logging(boolean) Logging} is enabled, the prefix to
print before each response header line that is reported received
from the server.
*/
public static final String
LOG_INPUT_PREFIX = " >> ";
private static final String
WHITESPACE = " \t",
HTTP_VERSION_DELIMITERS = "/" + WHITESPACE,
FIELD_CONTENT_DELIMITERS = ":;,&" + WHITESPACE,
VALUE_DELIMITERS = "=" + WHITESPACE,
EOL = "\r\n";
//------------------------------------------------------------------------------
// DEBUG control
private static final int
DEBUG_OFF = 0,
DEBUG_CONSTRUCTORS = 1 << 0,
DEBUG_ACCESSORS = 1 << 1,
DEBUG_SEND = 1 << 2,
DEBUG_HELPERS = 1 << 3,
DEBUG_HEADERS = 1 << 4,
DEBUG_DATA = 1 << 5,
DEBUG_RECEIVE = 1 << 6,
DEBUG_CONNECT = 1 << 7,
DEBUG_BUFFERS = 1 << 8,
DEBUG_IIS = 1 << 9,
DEBUG_ALL = -1,
DEBUG = DEBUG_OFF;
// DEBUG = DEBUG_ALL & ~DEBUG_DATA & ~DEBUG_HEADERS;
/*==============================================================================
Constructors
*/
/** Constructs an HTTP_ImageInputStream on a URL.
After a successful {@link #Connect(URL) connect}ion to the server has
been established, a data storage buffer is {@link #Allocate_Buffer(int)
allocated} with the {@link #DEFAULT_BUFFER_SIZE} capacity. Then the
validity of the source is {@link #Check_Source() checked}. If the
source can not be confirmed the connection to the server is closed.
Otherwise, if the server response to the source check contains a
{@link #Content_Length() content length} that is used to set the
size of the source file.
@param url The URL to use to access the source file.
@throws IllegalArgumentException If the URL does not specify the
http protocol nor provide a source file pathname.
@throws UnknownHostException If the hostname of the URL can not
be resolved to an internet address.
@throws FileNotFoundException If the source was not found on the server.
@throws ProtocolException If an HTTP {@link #Status() Status}
protocol error was returned by the server.
@throws IOException If the server connection could not be established.
*/
public HTTP_ImageInputStream
(
URL url
)
throws IOException, UnknownHostException, IllegalArgumentException
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
{
System.out.println
(">>> HTTP_ImageInputStream: URL " + url);
Logging (true);
}
Connect (url);
Allocate_Buffer (DEFAULT_BUFFER_SIZE);
int
source_status = Check_Source ();
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Source status: " + source_status);
int
attempt = 0;
while (source_status >= SUCCESS_STATUS_LIMIT &&
attempt < MAX_RECONNECT_ATTEMPTS)
{
if (Redirect ())
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Redirected to " + Source_URL);
source_status = Check_Source ();
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Source status: " + source_status);
++attempt;
}
else
break;
}
if (source_status >= SUCCESS_STATUS_LIMIT)
{
close ();
if (source_status == SOURCE_NOT_FOUND_STATUS)
throw new FileNotFoundException (ID + '\n'
+ "URL not found: " + url);
else if (attempt == MAX_RECONNECT_ATTEMPTS)
throw new ProtocolException (ID + '\n'
+ "Too many server redirects for source at " + url + '\n'
+ "Last attempt was to URL " + Source_URL);
else
throw new ProtocolException (ID + '\n'
+ "Status " + source_status + " for source at " + url);
}
long
length = Content_Length ();
if (length >= 0)
Source_Size = length;
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< HTTP_ImageInputStream: Source size = " + Source_Size);
}
/*==============================================================================
Accessors
*/
/** Get the URL used to access the source.
@return The source URL.
*/
public URL Source_URL ()
{return Source_URL;}
/** Get the source server hostname.
@return The hostname String for the server.
*/
public String Server_Hostname ()
{return Server_Hostname;}
/** Get the source pathname.
@return The pathname String where the source to be found by the server.
*/
public String Source_Pathname ()
{return Source_Pathname;}
/** Get the HTTP user agent name reported to the server.
@return The user agent name String.
@see #User_Agent(String)
*/
public String User_Agent ()
{return User_Agent;}
/** Set the HTTP user agent name to be reported to the server.
Every time a request is sent to the server a "User-Agent" message
is included. This information can be used by the server to gather
statistics on it's use by the identified client agent. When an
HTTP_ImageInputStream object is constructed the user agent is
set as the {@link #Default_User_Agent}.
@param name The user agent name String. If this is null, the
{@link #Default_User_Agent} will be assigned.
@return This HTTP_ImageInputStream.
*/
public HTTP_ImageInputStream User_Agent
(
String name
)
{
if (name == null ||
name.length () == 0)
User_Agent = Default_User_Agent;
else
User_Agent = name;
return this;
}
/** Get the default user agent that will be used with new
HTTP_ImageInputStream objects.
@return The default user agent String.
@see #User_Agent(String)
*/
public static String Default_User_Agent ()
{return Default_User_Agent;}
/** Set the default user agent that will be used with new
HTTP_ImageInputStream objects.
@param name The user agent name String. If this is null, the
{@link #DEFAULT_USER_AGENT} will be assigned.
@see #User_Agent(String)
*/
public static void Default_User_Agent
(
String name
)
{
if (name == null ||
name.length () == 0)
Default_User_Agent = DEFAULT_USER_AGENT;
else
Default_User_Agent = name;
}
/** Get the total number of bytes sent to the server so far.
@return A long value that is the number of bytes that have been
sent to the server.
*/
public long Total_Sent ()
{return Total_Sent;}
/** Get the total number of bytes received from the server so far.
@return A long value that is the number of bytes that have been
received from the server.
*/
public long Total_Received ()
{return Total_Received;}
/** Check if server communication logging is enabled.
@return true if logging is enabled; false otherwise.
@see #Logging(boolean)
*/
public boolean Logging ()
{return Logging;}
/** Enable or disable server communication logging.
When logging is enabled, each message {@link #Send(String) sent} to
the server is printed to stdout preceded by the {@link
#LOG_OUTPUT_PREFIX} String, and each {@link #Headers() header}
response line is printed preceded by the {@link #LOG_INPUT_PREFIX}
String. In addition, the amount of data content {@link #Receive()
receive}d is printed on a ling after a LOG_INPUT_PREFIX.
@param enabled true if logging is to be enabled; false otherwise.
@return This HTTP_ImageInputStream.
*/
public HTTP_ImageInputStream Logging
(
boolean enabled
)
{
Logging = enabled;
return this;
}
/*==============================================================================
ImageInputStream
*/
// Required method.
/** Read a source byte.
The {@link #getBitOffset() bit offset} is set to zero.
@return The next byte value from the source. This will be -1
if the current source location is end of file.
@throws IOException If access to the source is closed or there was a
problem obtaining source data.
*/
public int read ()
throws IOException
{
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
(">>> HTTP_ImageInputStream.read:\n"
+" stream location " + Stream_Location () + " (" + streamPos + ')');
int
datum = -1;
if (Stream_Location () < Source_Size)
{
if (Image_Buffer.remaining () > 0 ||
Fetch (INPUT_INCREMENT) > 0)
{
// Required ImageInputStream functionality.
bitOffset = 0;
++streamPos;
datum = (int)Image_Buffer.get () & 0xFF;
}
}
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
("<<< HTTP_ImageInputStream.read: 0x" + Integer.toHexString (datum));
return datum;
}
// Required method.
/** Read a sequence of source bytes and store them in an array.
The number of bytes actually read may be less than the specified
length. The length will be reduced to the smaller of the amount
of space in the data array following the offset or the amount of
buffered data remaining after an attempt to provide length bytes.
The {@link #getBitOffset() bit offset} is set to zero.
The current source input location is advanced by the amount of
data read.
@param data The byte array into which the data is to be stored.
@param offset The offset of the array where the first byte read is
to be stored.
@param length The number of bytes to read.
@return The number of bytes read and stored. This will be -1 if the
current source location is end of file.
@throws NullPointerException If the data array is null.
@throws IndexOutOfBoundsException If the offset or length are
negative, or the offset is greater than the length of the data
array.
@throws IOException If access to the source is closed or there was a
problem obtaining source data.
@see #Fetch(int)
*/
public int read
(
byte[] data,
int offset,
int length
)
throws IOException
{
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
(">>> HTTP_ImageInputStream.read: data"
+ data + ", size " + data.length
+ ", offset " + offset + ", length " + length + '\n'
+" stream location " + Stream_Location () + " (" + streamPos + ')');
int
amount = -1;
if (Stream_Location () < Source_Size)
{
if (data == null)
throw new NullPointerException (ID + '\n'
+ "Attempt to read into a null data array.");
if (length < 0 ||
offset < 0 ||
offset >= data.length)
throw new IndexOutOfBoundsException (ID + '\n'
+ "Attempt to read into array of length " + data.length
+ " at offset " + offset
+ " for amount " + length + '.');
if ((offset + length) > data.length)
{
length = data.length - offset;
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
(" length clipped to array amount after offset: " + length);
}
int
additional = length - Image_Buffer.remaining ();
if (additional >= 0)
{
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
(" additional buffer amount wanted: " + additional);
if (Data_End_Location () < Source_Size)
{
// Round up to the nearest INPUT_INCREMENT.
additional += INPUT_INCREMENT - (additional % INPUT_INCREMENT);
if (Fetch (additional) <= 0)
{
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
("<<< HTTP_ImageInputStream.read: " + amount);
return amount;
}
}
}
if (length > Image_Buffer.remaining ())
{
length = Image_Buffer.remaining ();
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
(" length clipped to buffer amount remaining: " + length);
}
// Required ImageInputStream functionality.
bitOffset = 0;
streamPos += length;
Image_Buffer.get (data, offset, length);
amount = length;
}
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
("<<< HTTP_ImageInputStream.read: " + amount);
return amount;
}
/** Determine if the source data is cached.
@return true
*/
public boolean isCached ()
{return true;}
/** Determine if the source data is cached in memory.
@return true
*/
public boolean isCachedMemory ()
{return true;}
/** Get the size of the source file.
@return The size of the source file. This will be -1 if the size
is not yet known. This information may become available after
further interaction with the server providing access to the
source file.
*/
public long length ()
{
if (Source_Size == NO_SOURCE_SIZE)
return -1;
return Source_Size;
}
/** Discard buffered data before a source location.
@param location The source file offset before which buffered
data is to be discarded. If the location is before the beginning
of buffered data nothing is done.
@throws IOException If the source file stream is closed.
@throws IndexOutOfBoundsException If the location is greater than
the current {@link #getStreamPosition() source input location}.
@see #Drain(int)
*/
public void flushBefore
(
long location
)
throws IOException
{
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
(">>> HTTP_ImageInputStream.flushBefore: " + location);
if (location > Stream_Location ())
throw new IndexOutOfBoundsException (ID + '\n'
+ "Flush location " + location
+ " is beyond the current stream location of "
+ Stream_Location () + '.');
if (location > Buffer_Location ())
Drain (Position_for_Location (location));
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
("<<< HTTP_ImageInputStream.flushBefore");
}
/** Set the current source file location where the next byte will be read.
The {@link #getBitOffset() bit offset} is set to zero.
@param location The source file offset for the image buffer's
next read position. A location less than zero will be set to zero;
a location greater than the source file size will be set to the
end of the source file.
@throws IOException If the source file stream is closed or there was
a problem reading data from from the source.
@see #Stream_Location(long)
*/
public void seek
(
long location
)
throws IOException
{
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
(">>> HTTP_ImageInputStream.seek: " + location);
Stream_Location (location);
bitOffset = 0;
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
("<<< HTTP_ImageInputStream.seek");
}
/** All access to the source is closed.
@throws IOException If there was a problem closing the server
input or output streams or the socket connection.
*/
public void close ()
throws IOException
{
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
(">>> HTTP_ImageInputStream.close");
String
message = null;
if (Server_Input != null)
{
try {Server_Input.close ();}
catch (IOException exception)
{
message = ID + '\n'
+ "Unable to close the server input stream.\n"
+ exception.getMessage ();
}
}
if (Server_Writer != null)
{
try {Server_Writer.close ();}
catch (IOException exception)
{
if (message == null)
message = ID;
message += "\n"
+ "Unable to close the server output stream.\n"
+ exception.getMessage ();
}
}
if (Server_Socket != null)
{
try {Server_Socket.setSoLinger (false, 0);}
catch (SocketException exception) {}
try {Server_Socket.close ();}
catch (IOException exception)
{
if (message == null)
message = ID;
message += "\n"
+ "Unable to close the server socket connection.\n"
+ exception.getMessage ();
}
}
Server_Socket = null;
Server_Writer = null;
Server_Input = null;
Source_Size = NO_SOURCE_SIZE;
System.gc ();
if (message != null)
throw new IOException (message);
if ((DEBUG & DEBUG_IIS) != 0)
System.out.println
("<<< HTTP_ImageInputStream.close");
}
/** Checks if the server connection is closed.
@return true if the server connection is closed; false otherwise.
*/
public boolean is_Closed ()
{return Server_Socket == null;}
/*==============================================================================
HTTP Client
*/
/** Connect to the server.
The specified URL checked for validity. If the URL does not specify a
port number, the {@link #DEFAULT_PORT} will be used.
N.B.: Establishing a new server connection causes any existing
connection to be closed and the source input location to be {@link
#Reset(long) Reset} to the beginning of the file.
@param url The URL to use in connection to the server.
@throws IllegalArgumentException If the URL does not specify the
http protocol nor provide a source file pathname.
@throws UnknownHostException If the hostname of the URL can not
be resolved to an internet address.
@throws IOException If the socket connection could not be established
or the input or output streams could not be opened.
@see #Reconnect()
*/
public void Connect
(
URL url
)
throws IOException
{
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(">>> HTTP_ImageInputStream.Connect: " + url);
// Protocol.
if (! "http".equals (url.getProtocol ()))
{
try {close ();}
catch (IOException e) {}
throw new IllegalArgumentException (ID + '\n'
+ "Invalid URL: " + url + '\n'
+ "Only the http protocol can be used.");
}
// Server hostname.
String
server_hostname = null;
InetAddress
address = null;
try
{
server_hostname = url.getHost ();
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Host name: " + server_hostname);
address = InetAddress.getByName (server_hostname);
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Host address: " + address);
}
catch (Exception exception)
{
try {close ();}
catch (IOException e) {}
throw new UnknownHostException (ID + '\n'
+ "Invalid URL: " + url + '\n'
+ "Unknown hostname.");
}
// Port number.
int
port = url.getPort ();
if (port < 0)
port = DEFAULT_PORT;
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Port number: " + port);
// Image pathname.
String
source_pathname = url.getPath ();
if (source_pathname.length () == 0 ||
source_pathname.equals ("/"))
{
try {close ();}
catch (IOException e) {}
throw new IllegalArgumentException (ID + '\n'
+ "Invalid URL: " + url + '\n'
+ "A source image pathname must be specified.");
}
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Image pathname: " + source_pathname);
// Server internet socket address.
InetSocketAddress
server_address = Server_Address;
Server_Address = new InetSocketAddress (address, port);
// Connect (or reconnect) to the server.
try {Reconnect ();}
catch (IOException exception)
{
// Try to restore the previous server connection.
Server_Address = server_address;
try {Reconnect ();}
catch (IOException except) {}
throw exception;
}
// Update the server URL connection information.
Source_URL = new URL
(
url.getProtocol (),
Server_Hostname = server_hostname,
port,
Source_Pathname = source_pathname
);
if (Source_Buffer != null)
Reset (0);
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
("<<< HTTP_ImageInputStream.Connect");
}
/** Reconnect to the server.
If a Socket for communication with the server exists it is closed.
A new Socket connection to the server is constructed. A maximum of
{@link #DEFAULT_CONNECT_TIMEOUT} milliseconds is allowed for the
connection to be established. Then input and output communication
streams with the server are opened over the Socket. Up to {@link
#MAX_RECONNECT_ATTEMPTS} connection attempts will be made. On the
last attempt, the first connection operation failure that occurs will
throw an IOException.
@throws IOException If a Socket could not be constructed on the
server address within the {@link #DEFAULT_CONNECT_TIMEOUT} time,
a Writer could not be constructed on the Socket or an InputStream
could not be constructed on the Socket.
*/
protected void Reconnect ()
throws IOException
{
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(">>> HTTP_ImageInputStream.Reconnect");
int
attempt = MAX_RECONNECT_ATTEMPTS;
while (attempt-- != 0)
{
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Attempt " + (MAX_RECONNECT_ATTEMPTS - attempt));
// Close the current socket.
if (Server_Socket != null)
{
if (Logging)
System.out.println (LOG_OUTPUT_PREFIX
+ "[Server reconnect]");
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Closing the current connection");
try {close ();}
catch (IOException exception) {}
/*
// Let the dust settle.
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Pausing "+ RECONNECT_WAIT + " ms");
try {this.wait (RECONNECT_WAIT);}
catch (InterruptedException exception) {}
*/
}
if (Server_Address == null)
// No addres for reconnection.
break;
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Server Socket.");
Server_Socket = new Socket ();
try {Server_Socket.connect (Server_Address, DEFAULT_CONNECT_TIMEOUT);}
catch (SocketTimeoutException exception)
{
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Socket connect timeout.");
try {close ();}
catch (IOException except) {}
if (attempt == 0)
throw new IOException (ID + '\n'
+ "Unable to connect to server at " + Server_Address + '\n'
+ "after waiting " + (DEFAULT_CONNECT_TIMEOUT / 1000)
+ " seconds.\n"
+ exception.getMessage ());
continue;
}
catch (IOException exception)
{
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" IOException: "+ exception.getMessage ());
try {close ();}
catch (IOException except) {}
if (attempt == 0)
throw new IOException (ID + '\n'
+ "Unable to make a socket connection to the server at "
+ Server_Address + '\n'
+ exception.getMessage ());
continue;
}
// Output stream.
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Server Writer.");
try
{
Server_Writer = new BufferedWriter
(new OutputStreamWriter
(Server_Socket.getOutputStream (), ENCODING_SCHEME),
HEADERS_BUFFER_SIZE);
}
catch (IOException exception)
{
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" IOException: "+ exception.getMessage ());
try {close ();}
catch (IOException e) {}
if (attempt == 0)
throw new IOException (ID + '\n'
+ "Unable to open an output stream to the server at "
+ Server_Address + '\n'
+ exception.getMessage ());
continue;
}
// Input stream.
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" Server Input.");
try {Server_Input = Server_Socket.getInputStream ();}
catch (IOException exception)
{
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(" IOException: "+ exception.getMessage ());
try {close ();}
catch (IOException e) {}
if (attempt == 0)
throw new IOException (ID + '\n'
+ "Unable to open an input stream from the server at "
+ Server_Address + '\n'
+ exception.getMessage ());
continue;
}
break;
}
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
("<<< HTTP_ImageInputStream.Reconnect");
}
/** Redirect the source URL.
@return true if the HTTP Status indicated a redirection (300-399)
and the redirection succeeded; false otherwise.
*/
private boolean Redirect ()
throws IOException
{
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
(">>> HTTP_ImageInputStream.Redirect");
boolean
redirected = false;
if (HTTP_Status >= 300 &&
HTTP_Status < 400)
{
String
source_location = Header_Content ("Location");
if (source_location != null)
{
Connect (new URL (source_location));
redirected = true;
}
}
if ((DEBUG & DEBUG_CONNECT) != 0)
System.out.println
("<<< HTTP_ImageInputStream.Redirect: " + redirected);
return redirected;
}
/*------------------------------------------------------------------------------
Buffer Management
*/
/** Source data buffer.
Two views of the same data are provided: A Source_Buffer and an
Image_Buffer.
The Source_Buffer is filled (put) by the Server_Input socket stream.
It's position is where the next data content - not header lines -
input byte will be placed. It's limit is the buffer capacity.
The Image_Buffer is used (get) to implement the ImageInputStream
interface. It's position is where the next ImageInputStream read byte
will be obtained; this is equivalent to the virtual stream location
in the {@link #Source_Pathname()} on the {@link #Server_Hostname()}.
It's limit is the end of valid source data in the buffer (i.e. the
buffer may not be full). This should be the same as the Source_Buffer
position.
The first byte of the buffer is located at Buffer_Location offset in
the source file. The streamPos variable in the ImageInputStreamImpl
base class must also be maintained as the offset in the source file
corresponding to the Image_Buffer position.
*/
private ByteBuffer
Source_Buffer = null,
Image_Buffer;
// Requirement: INPUT_INCREMENT < Source_Buffer.capacity
/** The amount of source data to {@link #Fetch(int) fetch} when
performing an automatic refresh of buffer contents.
*/
public static final int
INPUT_INCREMENT = 0x2000; // 8 KB.
/** The default buffer capacity to {@link #Allocate_Buffer(int) allocate}.
*/
public static final int
DEFAULT_BUFFER_SIZE = INPUT_INCREMENT << 4; // 128 KB.
/** Allocates a data storage buffer.
A ByteBuffer of the specified size (bytes) is allocated and cleared
(position set to zero and limit set to the capacity).
If there is no previously existing source buffer, the newly allocated
buffer is set as the source buffer. It is duplicated to provide the
image buffer view and the image buffer's limit is set to zero.
If there is a previously existing source buffer, all valid source
data is copied from it into the new buffer, up to the capacity of the
new buffer, and then the new buffer is set as the source buffer.
N.B.: If the new buffer capacity is less than the previous
buffer's valid data content, the excess data will be dropped. The
source buffer is duplicated onto the temporary buffer, the image
buffer limit and position copied over, and then the temporary buffer
is set as the image buffer. N.B.: If the previous image buffer
limit is greater than the new buffer capacity the new limit will be
the new capacity; the same applies to the image buffer position,
which would result in a corresponding move back of the logical stream
location. Garbage collection is initiated to recover the previous
buffer resources.
@param capacity The capacity of the new buffer. If less than
twice the {@link #INPUT_INCREMENT} it will be increased to this
value.
*/
public void Allocate_Buffer
(
int capacity
)
{
if (capacity < (2 * INPUT_INCREMENT))
capacity = 2 * INPUT_INCREMENT;
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
(">>> HTTP_ImageInput_Stream.Allocate_Buffer: " + capacity);
ByteBuffer
buffer = ByteBuffer.allocate (capacity);
buffer.clear (); // position = 0; limit = capacity.
if (Source_Buffer == null)
{
Source_Buffer = buffer;
Image_Buffer = Source_Buffer.duplicate ();
Image_Buffer.limit (0);
}
else
{
// Copy over the existing data.
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
(" Copying " + Source_Buffer.position () + " data buffer bytes");
Source_Buffer.flip ();
if (Source_Buffer.limit () > buffer.capacity ())
Source_Buffer.limit (buffer.capacity ());
buffer.put (Source_Buffer);
Source_Buffer = buffer;
// Replicate the image buffer view.
buffer = Source_Buffer.duplicate ();
if (Image_Buffer.position () > buffer.capacity ())
{
buffer.position (buffer.capacity ());
streamPos = Location_for_Position (buffer.capacity ());
}
else
buffer.position (Image_Buffer.position ());
if (Image_Buffer.limit () > buffer.capacity ())
buffer.limit (buffer.capacity ());
else
buffer.limit (Image_Buffer.limit ());
Image_Buffer = buffer;
// Free unused memory.
System.gc ();
}
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
("<<< HTTP_ImageInput_Stream.Allocate_Buffer");
}
/** Drain data from the buffer.
The logical location of the buffer in the source data stream is moved
forward by some amount. This has the effect of draining valid source
data from the front of the buffer and sliding the buffer forward
to a new location in the source file.
If the amount is less than or equal to zero, nothing is done.
If the amount is greater than or equal to the end of valid source
data in the buffer (image buffer limit), the buffer is simply (@link
#Empty() emptied}.
The remaining source data beyond the amount buffer index is moved to
the beginning of the buffer. The buffer's logical position is the
source data stream is moved forward by the amount of data removed
(the slide distance). The source buffer input position and image
buffer limit are reset to the new end of valid source data. The image
buffer position is moved back by the amount of of data removed.
However, if this new position would be less than zero it is set to
zero, and the current logical stream location is moved up by the
difference (i.e. to the buffer's logical position in the stream).
@param amount The amount of data to drain.
@return The amount of source data effectively removed from the buffer
(i.e. the slide distance).
*/
public int Drain
(
int amount
)
{
if (amount <= 0)
return 0;
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println (">>> HTTP_ImageInputStream.Drain: " + amount);
/* N.B.: Image_Buffer limit == Source_Buffer position
And they must remain the same.
*/
if (amount >= Image_Buffer.limit ())
{
// Empty the buffer.
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
("<<< HTTP_ImageInputStream.Drain: emptied");
return Empty ();
}
// Post-move location in the source data stream of the buffer.
Buffer_Location (Buffer_Location () + amount);
// Post-move current stream location buffer index.
int
position = Image_Buffer.position () - amount;
if (position < 0)
{
position = 0;
/*
Data is being drained beyond the current stream location.
The stream location must be shifted up accordingly.
*/
streamPos = Buffer_Location ();
}
// Post-move end of valid source data buffer index.
int
limit = Image_Buffer.limit () - amount;
// Move the data.
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
(" Moving data buffer bytes ["
+ amount + '-' + Source_Buffer.position ()
+ ") to [0-" + Source_Buffer.position () + ')');
Source_Buffer.limit (Source_Buffer.position ()); // End of data.
Source_Buffer.position (amount); // Start of data.
Image_Buffer.position (0); // Destination.
Image_Buffer.put (Source_Buffer); // Move the data.
// Reset the pointers.
Image_Buffer.position (position);
Image_Buffer.limit (limit);
Source_Buffer.position (limit);
Source_Buffer.limit (Source_Buffer.capacity ());
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
(" Source_Buffer.position = " + Source_Buffer.position () + '\n'
+" Source_Buffer.limit = " + Source_Buffer.limit () + '\n'
+" Image_Buffer.position = " + Image_Buffer.position () + '\n'
+" Image_Buffer.limit = " + Image_Buffer.limit () + '\n'
+" Buffer_Location = " + Buffer_Location () + '\n'
+" streamPos = " + streamPos + '\n'
+"<<< HTTP_ImageInputStream.Drain: " + amount);
return amount;
}
/** Drain source data before the current stream position.
This has the same effect as {@link #Drain(int) drain}ing all data
before the current stream (image buffer) position.
@return The amount of source data effectively removed from the buffer
(i.e. the slide distance).
@see #Drain(int)
*/
public int Drain ()
{return Drain (Image_Buffer.position ());}
/** Empty the buffer of all source data.
The buffer's logical location in the source data stream is moved up
to the end of source data content in the buffer, and the current
source data stream position is set to this location. The source
buffer position is set to the beginning of the buffer as are the
image buffer position and data limit. This has the same effect as
{@link #Drain(int) drain}ing all the data content from the buffer.
@return The amount of source data effectively removed from the buffer
(i.e. the slide distance).
*/
public int Empty ()
{
int
amount = Image_Buffer.limit ();
if (amount > 0)
Reset (Data_End_Location ());
return amount;
}
/** Reset the buffer to a new source location and empty it.
@param location The new buffer and stream position location.
*/
public void Reset
(
long location
)
{
Buffer_Location =
streamPos = location;
Source_Buffer.position (0);
Image_Buffer.limit (0);
}
/** Get the virtual source location of the beginning of the buffer.
@return The source file offset where the buffer begins.
*/
public long Buffer_Location ()
{return Buffer_Location;}
/** Set the virtual source location of the beginning of the buffer.
N.B.: Changing the virtual source location of the buffer will
affect all other buffer virtual locations because they are relative
to the buffer location.
@param location The source file offset where the buffer begins.
A value less than zero is set to zero; a value greater than the
size of the source file is set to the size of the source file.
*/
protected void Buffer_Location
(
long location
)
{
if (location < 0)
location = 0;
else
if (location > Source_Size)
location = Source_Size;
Buffer_Location = location;
}
/** Get the virtual source location where the next image buffer will be
read.
@return The current image buffer virtual source file offset location.
*/
protected long Stream_Location ()
{return Location_for_Position (Image_Buffer.position ());}
/** Set the virtual source location where the next image buffer will be
read.
If the location is within the range of buffered source data the
image buffer position is simply moved to the corresponding position.
The location is less than zero, zero will be used; if it is greater
than the size of the source file, the location will be set to the
end of the source data.
If the location is the same as the current virtual source stream
location nothing is done.
If the location is before the stream location of the first byte in
the image buffer and within {@link #INPUT_INCREMENT} bytes of the
beginning of the buffer, the current buffered data will be shifted
up by INPUT_INCREMENT bytes and the resulting gap at the beginning
of the buffer filled with data {@link #Fetch(int) Fetch}ed from the
corresponding offset range of the source file. The image buffer
position is then set to correspond to the new stream location.
If the location is beyond the end of buffered data, but not beyond
the end of the maximum capacity of the buffer, and within
INPUT_INCREMENT bytes of the end of data, up to INPUT_INCREMENT
additional bytes (not more than would fill the buffer to capacity)
are {@link #Fetch(int) Fetch}ed from the source file to extend the
buffered data. The image buffer position is then set to correspond
to the new stream location.
For any other case the buffer is simply {@link #Reset(long) Reset}
to the new location.
The effect is a random access seek to any location within the
source file, with data pre-fetch optimization when the new location
is near the currently buffered data.
@param location The source file offset for the image buffer's
next read position.
*/
public void Stream_Location
(
long location
)
throws IOException
{
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
(">>> HTTP_ImageInputStream.Stream_Location: " + location);
if (location >= Buffer_Location () &&
location <= Data_End_Location ())
{
// The new location is within the available buffered data.
Image_Buffer.position ((int)(location - Buffer_Location ()));
streamPos = location;
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
(" The location is within the buffer.\n"
+"<<< HTTP_ImageInputStream.Stream_Location: " + streamPos);
return;
}
if (location < 0)
location = 0;
else
if (location > Source_Size)
location = Source_Size;
if (location == streamPos)
{
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
(" The location is unmoved.\n"
+"<<< HTTP_ImageInputStream.Stream_Location: " + streamPos);
return;
}
if (location < Buffer_Location ())
{
// Move the logical stream location back before the buffer location.
if ((Buffer_Location () - location) <= INPUT_INCREMENT)
{
/* The seek distance is no greater than the input increment.
Move data an input increment to prevent inefficient "creep".
Make a hole for the input data by shifting the existing data
up so that it will be contiguous with the new data that is
read into the hole.
Data is moved from the upper end to prevent data overlap.
*/
int
source = Image_Buffer.limit () - 1, // Source byte index.
target = source + INPUT_INCREMENT; // Destination index.
if (target >= Image_Buffer.capacity ())
{
// Clip off the excess data.
source -= target - Image_Buffer.capacity () + 1;
target = Image_Buffer.capacity () - 1;
}
Image_Buffer.limit (target + 1); // New end of data index.
// Move the data.
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
(" Moving data buffer bytes [0-" + (source + 1)
+ ") to [" + (Image_Buffer.limit () - source)
+ '-' + (target + 1) + ')');
while (source >= 0)
Image_Buffer.put (target--, Image_Buffer.get (source--));
// Fill the hole with an input increment of source data.
target = Image_Buffer.limit (); // Save end of data position.
Reset (Buffer_Location () - INPUT_INCREMENT);
Fetch (INPUT_INCREMENT);
// Reset the buffer pointers.
Source_Buffer.position (target); // Restore end of data position.
Image_Buffer.limit (target);
Image_Buffer.position (Position_for_Location (location));
streamPos = location;
}
else
// The seek distance is larger than the input increment.
Reset (location);
}
else
{
// Move the logical location forward beyond the end of data.
if (location < Location_for_Position (Image_Buffer.capacity ()) &&
(location - INPUT_INCREMENT) < Data_End_Location ())
{
// The new location is within an INPUT_INCREMENT of end of data.
int
amount = INPUT_INCREMENT;
if ((Image_Buffer.limit () + amount) > Image_Buffer.capacity ())
amount = Image_Buffer.capacity () - Image_Buffer.limit ();
Fetch (amount);
Image_Buffer.position (Position_for_Location (location));
streamPos = location;
}
else
// The seek distance is larger than the input increment.
Reset (location);
}
if ((DEBUG & DEBUG_BUFFERS) != 0)
System.out.println
(" Source_Buffer.position = " + Source_Buffer.position () + '\n'
+" Source_Buffer.limit = " + Source_Buffer.limit () + '\n'
+" Image_Buffer.position = " + Image_Buffer.position () + '\n'
+" Image_Buffer.limit = " + Image_Buffer.limit () + '\n'
+" Buffer_Location = " + Buffer_Location () + '\n'
+" streamPos = " + streamPos + '\n'
+"<<< HTTP_ImageInputStream.Stream_Location: " + streamPos);
}
/** Get the virtual source location of the end (exclusive) of buffered
data.
@return The source file offset where buffered data ends.
*/
public long Data_End_Location ()
{return Location_for_Position (Image_Buffer.limit ());}
/** Set the virtual source location of the end (exclusive) of buffered
data.
N.B.: If the new location is less than the buffer's current
virtual source location, the virtual source location will also be
moved to the new location. This enforces the constraint that the
virtual source location is always less than or equal to the end of
data location.
@param location The source file offset where the end of buffered
data is located. The location is clipped to produce a buffer
position with the range of the buffer capacity.
*/
protected void Data_End_Location
(
long location
)
{
int
index = Position_for_Location (location);
if (index < 0)
index = 0;
else
if (index > Image_Buffer.capacity ())
index = Image_Buffer.capacity ();
Image_Buffer.limit (index);
Source_Buffer.position (index);
}
/** Convert a buffer position to a virtual source location.
@param position A buffer position int.
@return A source location long.
*/
protected long Location_for_Position
(
int position
)
{return Buffer_Location () + position;}
/** Convert a virtual source location to a buffer position.
@param location A source location long.
@return A buffer position int.
*/
protected int Position_for_Location
(
long location
)
{return (int)(location - Buffer_Location ());}
/** Clip a source location to the currently buffered data range.
@param location A source location long.
@return The source location clipped to the range of buffered data.
*/
public long Image_Buffer_Range
(
long location
)
{
if (location < Buffer_Location ())
return Buffer_Location ();
if (location < Data_End_Location ())
return location;
return Data_End_Location ();
}
/** Test if a source location is in the range of buffered data.
The buffered data range begins at the {@link #Buffer_Location()}
(inclusive) and extends to the {@link #Data_End_Location()} (exclusive).
@param location A source location long.
@return true if the location is the range of buffered data; false
otherwise.
*/
public boolean in_Image_Buffer_Range
(
long location
)
{
return
location >= Buffer_Location () &&
location < Data_End_Location ();
}
/*------------------------------------------------------------------------------
Request
*/
/** Check the server status of the source.
A "HEAD" request for the source file is made to the server. The
reponse to a "HEAD" request will contain all the HTTP headers of a
normal request, but no data content will be included.
If access to the server is closed, then the last HTTP status value
will be returned. If no HTTP status value was ever obtained zero
will be returned. If an end of file condition is encountered will
communicating with the server, -1 will be returned. If some other
IOException is thrown, -2 will be returned. If any other Exception
is thrown, -3 will be returned.
The HTTP status when the source file is correctly found is less than
{@link #SUCCESS_STATUS_LIMIT}. If the source file is not found the
status will be {@link #SOURCE_NOT_FOUND_STATUS}.
@return The HTTP response status.
*/
public int Check_Source ()
{
if ((DEBUG & DEBUG_SEND) != 0)
System.out.println
(">>> HTTP_ImageInputStream.Check_Source");
if (! is_Closed ())
{
try
{
Request ("HEAD", Source_Pathname);
End_Request ();
Headers ();
}
catch (Exception exception)
{
HTTP_Status =
((exception instanceof EOFException) ? -1 :
((exception instanceof IOException) ? -2 : -3
));
}
}
if ((DEBUG & DEBUG_SEND) != 0)
System.out.println
("<<< HTTP_ImageInputStream.Check_Source: " + HTTP_Status);
return HTTP_Status;
}
/** Fetch source data from the server (absolute fetch).
The data will be fetched from the source file beginning at the start
location up to, but not including, the end location.
If the start location is within the buffered source data range it is
moved up to the end of data location. If the start location is at or
beyond the end of the source file, nothing is done and zero is
returned. If, after range clipping, the start location is not the
same as the end of source data location in the buffer, the buffer is
is {@link #Reset(long) reset} to the start location. The end
location will be clipped to the size of the source file.
If communication with the server is lost during the data fetch, a
{@link #Reconnect() reconnect}ion will be tried. If this succeeds
the data fetch will be repeated.
@param start The source file offset (inclusive) where the data
fetch is to begin.
@param end The source file offset (exclusive) where the data
fetch is to end.
@return The amount of data received from the server.
@throws IllegalArgumentException If start is less than zero or
greater than end.
@throws IOException If there was a problem communicating with the
server.
@see #Request_Source_Data(long, long)
@see #Receive()
*/
public int Fetch
(
long start,
long end
)
throws IllegalArgumentException, IOException
{
if ((DEBUG & DEBUG_SEND) != 0)
System.out.println
(">>> HTTP_ImageInputStream.Fetch: " + start + '-' + end);
if (Server_Writer == null)
throw new IOException (ID + '\n'
+ "The server connection is closed.");
int
received = 0;
if (start < 0 ||
start > end)
throw new IllegalArgumentException (ID + '\n'
+ "Invalid source data range to fetch: " + start + '-' + end);
if (in_Image_Buffer_Range (start))
start = Data_End_Location ();
if (start < Source_Size)
{
if (end > Source_Size)
end = Source_Size;
if (start != Data_End_Location ())
// Reset the buffer to the new start location.
Reset (start);
Request_Source_Data (start, end);
received = Receive ();
if (received < 0)
{
try
{
Reconnect ();
Request_Source_Data (start, end);
received = Receive ();
if (received < 0)
{
throw new IOException (ID + '\n'
+ "Sever connection lost while fetching from "
+ start + " to " + end);
}
}
catch (IOException exception)
{
throw new IOException (exception.getMessage () + '\n'
+ "Sever connection lost while fetching from "
+ start + " to " + end);
}
}
}
if ((DEBUG & DEBUG_SEND) != 0)
System.out.println
("<<< HTTP_ImageInputStream.Fetch: " + received);
return received;
}
/** Fetch source data from the server (relative fetch).
The data will be fetched from the source file starting at the
current end of source data location in the buffer.
@param amount The amount of data to fetch.
@return The amount of data fetched.
@throws IOException If there was a problem send or receiving data
from the server.
*/
public int Fetch
(
int amount
)
throws IOException
{return Fetch (Data_End_Location (), Data_End_Location () + amount);}
/** Get a range of source data.
N.B.: No check is made of the validity of the source range.
@param start The file offset of the start of the data range
(inclusive).
@param end The file offset of the end of the data range
(exclusive).
@return This HTTP_ImageInputStream.
@throws IllegalArgumentException If start is greater than end.
@throws BufferOverflowException If the (end - start) amount is
greater than Integer.MAX_VALUE.
@throws IOException If there was a problem sending the request
to the server.
*/
protected HTTP_ImageInputStream Request_Source_Data
(
long start,
long end
)
throws IllegalArgumentException, BufferOverflowException, IOException
{
if ((DEBUG & DEBUG_SEND) != 0)
System.out.println
(">>> HTTP_ImageInputStream.Request_Source_Data: " + start + "-" + end);
if (start > end)
throw new IllegalArgumentException (ID + '\n'
+ "Invalid source data range request: " + start + "-" + end);
if ((end - start) > (long)Integer.MAX_VALUE)
throw new BufferOverflowException ();
if (start < end)
{
Request ("GET", Source_Pathname);
// N.B.: Request range limits are inclusive.
Send ("Range: bytes=" + start + "-" + --end);
Send ("Accept-Encoding: identity");
End_Request ();
}
if ((DEBUG & DEBUG_SEND) != 0)
System.out.println
("<<< HTTP_ImageInputStream.Request_Source_Data");
return this;
}
/** Issue a Request preamble to the server.
After the HTTP formatted request is {@link #Send(String) sent} to
the server, the Host, User-Agent, and Cache-Control (no-cache)
requests are also sent. N.B.: The request sequence has not
been {@link #End_Request() ended}.
@param method The request method String. This is typically "GET".
@param request The request operation.
@see #Send(String)
*/
protected void Request
(
String method,
String request
)
throws IOException
{
if ((DEBUG & DEBUG_SEND) != 0)
System.out.println
(">>> HTTP_ImageInputStream.Request: " + method + ' ' + request);
Send (method + ' ' + request + ' ' + HTTP_VERSION);
Send ("Host: " + Server_Hostname + ':' + Server_Address.getPort ());
Send ("User-Agent: " + User_Agent);
Send ("Cache-Control: no-cache");
if ((DEBUG & DEBUG_SEND) != 0)
System.out.println
("<<< HTTP_ImageInputStream.Request");
}
/** Send the end-of-request sequence to the server.
An single empty line is sent.
*/
protected void End_Request ()
throws IOException
{Send ("");}
/** Send a message line to the server.
The message is expected to be a single line to be sent to the
server. An end of line sequence will be appended to the message that is
sent if it is not already present.
If {@link #Logging(boolean) Logging} is enabled the message,
preceded by the {@link #LOG_OUTPUT_PREFIX}, will be printed to
stdout before it is sent to the server.
@param message The message String to be sent.
@throws IOException If the connection to the server is closed or
there was a problem sending the message.
*/
protected void Send
(
String message
)
throws IOException
{
if (is_Closed ())
throw new IOException (ID + '\n'
+ "The server connection is closed.");
if (message.length () == 0 ||
message.charAt (message.length () - 1) != '\n')
message += EOL;
Server_Writer.write (message);
Server_Writer.flush ();
Total_Sent += message.length ();
if (Logging)
System.out.print (LOG_OUTPUT_PREFIX + message);
}
/*------------------------------------------------------------------------------
Response
*/
/** Receive a response to a server request.
Server interaction always occurs in {@link #Request(String,String)
Request}-Receive pairs. After a Request has been sent it is necessary
to Receive the response from the server. The first part of the
response is sequence of one or more HTTP header lines. If a
Content-Length line is present the header lines are followed by data
content of Content-Length bytes.
If the HTTP response headers contain a {@link #Status() Status}
value that is less than 300, the data content is read into the
Source_Buffer starting at its current position. However, if the
amount of free space remaining in the buffer (buffer storage not
occupied by valid data
content; i.e. locations [position, limit), where limit == capacity)
is less than the Content-Length, more buffer space is first provided.
Space to store data content in the buffer is provided by {@link
#Drain() drain}ing away data from the beginning of the buffer
before the current source stream position.
@return The amount of source data received, or -1 if EOF was
encountered before any data was received.
*/
protected int Receive ()
throws IOException
{
if ((DEBUG & DEBUG_RECEIVE) != 0)
System.out.println (">>> HTTP_ImageInputStream.Receive");
// Get the HTTP headers.
try {Headers ();}
catch (EOFException exception)
{
if ((DEBUG & DEBUG_RECEIVE) != 0)
System.out.println ("<<< HTTP_ImageInputStream.Receive: -1");
return -1;
}
long
content_length = Content_Length ();
if (content_length > Integer.MAX_VALUE)
{
/* Too much data content!
This should never happen. But if it does something is wrong
and the Server_Input is now jammed with a huge queue of
data that must be dumped. Instead of locking up the user
application needlessly reading it all in, the connection to
the server will be closed and a BufferOverflowException
thrown.
*/
close ();
throw new BufferOverflowException ();
}
Range
range = Content_Range ();
int
amount,
received = 0,
length = (int)content_length;
if (length > 0)
{
if (Status () < 300)
{
if ((DEBUG & DEBUG_RECEIVE) != 0)
System.out.println
(" Response status " + Status () + '\n'
+" Content range: " + range + '\n'
+" Content length: " + length);
if (range.Start != Data_End_Location ())
{
if ((DEBUG & DEBUG_RECEIVE) != 0)
System.out.println
(" Content is not contiguous with buffer content.\n"
+" Buffer reset to location " + range.Start);
Reset (range.Start);
}
if (length > Source_Buffer.remaining ())
{
if ((DEBUG & DEBUG_RECEIVE) != 0)
System.out.println
(" Only " + Source_Buffer.remaining ()
+ " bytes of free buffer space remaining.");
// More buffer space needed. Drain the buffer.
Drain ();
if (length > Source_Buffer.remaining ())
{
/* Even more buffer space needed.
Allocate a larger buffer that is a multiple
of the INPUT_INCREMENT.
*/
amount = length - Source_Buffer.remaining ();
amount += Source_Buffer.capacity () + INPUT_INCREMENT
- (amount % INPUT_INCREMENT);
Allocate_Buffer (amount);
}
}
while (received < length)
{
amount = length - received;
if ((amount = Server_Input.read
(Source_Buffer.array (), Source_Buffer.position (), amount))
< 0)
break;
if ((DEBUG & DEBUG_DATA) != 0)
System.out.println
(" Got " + amount + " -\n"
+"-->|"
+ new String_Buffer (new String (Source_Buffer.array (),
Source_Buffer.position (), amount))
.special_to_escape ()
+ "|<--");
Data_End_Location (Data_End_Location () + amount);
received += amount;
Total_Received += amount;
}
if (Logging)
System.out.println (LOG_INPUT_PREFIX +
"Received " + received + " of " + length + " bytes.");
}
else
{
if ((DEBUG & DEBUG_RECEIVE) != 0)
System.out.println
(" Response status " + Status () + '\n'
+" Skipping " + length + " bytes.");
Server_Input.skip (length);
}
}
if ((DEBUG & DEBUG_RECEIVE) != 0)
System.out.println ("<<< HTTP_ImageInputStream.Receive: " + received);
return received;
}
/*------------------------------------------------------------------------------
HTTP Response Headers
*/
/** Get the HTTP response headers from the server.
After a {@link #Request(String, String) Request} has been sent to the
server - probably followed by {@link #Send(String) Send}ing
additional request messages - and {@link #End_Request() End}ed, the
server response will begin with a sequence of HTTP headers. Each
response line up to, but not including, an empty line will be added
to a Vector of HTTP Headers in which each element is itself a Vector
containing the header name and content. Note: A header line can be
wrapped across multiple response lines; the wrapped line(s) begin
with whitespace. In addition, a header with the same name as a
previous header will have its content appended to previous header.
This guarantees that each header in the Vector of HTTP Headers will
have a unique name.
Before the header lines are accumulated the HTTP Headers Vector is
cleared and the HTTP response {@link #Status() Status} is reset to
zero. As the header lines are being accumulated the HTTP response
status will be updated if it is found. In addition, the {@link
#Source_Size() source file size} will also be set if it is found the
response.
@return The HTTP response status.
@throws IOException If an problem was encountered while reading
response lines. This will be an EOFException if an end of
input from the server was encountered.
*/
protected int Headers ()
throws IOException
{
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println (">>> HTTP_ImageInputStream.Headers");
// Reset for new headers from the server.
HTTP_Headers.clear ();
HTTP_Status = 0;
String
line,
header = "";
while (true)
{
// Get a line from the server response.
line = Response_Line ();
if (line.length () == 0 ||
WHITESPACE.indexOf (line.charAt (0)) < 0)
{
// Start of a new header. Add the previous header.
Header_Add (header);
if (line.length () == 0)
// Last line.
break;
// Reset the header to the current line.
header = line;
}
else
{
// Continuation of wrapped line.
if (header.length () == 0)
/* The first line can't be wrapped.
Set the header to the current line trimmed of whitespace.
*/
header = line.trim ();
else
// Append this line to the header.
header += line;
}
}
// Attempt to update the HTTP response status.
Status ();
if (Source_Size == NO_SOURCE_SIZE)
// Attempt to set the source file size.
Source_Size ();
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println ("<<< HTTP_ImageInputStream.Headers: " + HTTP_Status);
return HTTP_Status;
}
/** A server response header line is read from the server.
One byte at a time is read from the Server_Input until an end-of-line
or end-of-file condition is encountered. All bytes up to, but not
including, the end-of-line delimiter(s) are accumulated as characters
in a StringBuffer.
An end-of-line condition is identified by a '\n' or '\r' character. A
'\r' may optionally be followed by a '\n' character which is treated
as an additional end-of_line delimiter. The end-of-line characters
are not included in the returned String. The Server_Input is left
positioned at the next byte after the end-of-line delimiter(s).
If an end-of-file condition is encountered after one or more line
characters have been accumulated, a String is returned with those
characters. However, if no characters have been accumulated an
EOFException is thrown.
@return A String containing the line that was read.
@throws IOException if there was a problem reading from the
Server_Input. This will ba an EOFException if an end-of-file
condition was encountered before any line characters were read.
*/
private String Response_Line ()
throws IOException
{
StringBuffer
line = new StringBuffer ();
int
datum;
Line:
while ((datum = Server_Input.read ()) >= 0)
{
++Total_Received;
switch (datum)
{
case '\r':
// Probable NL after CR.
Server_Input.mark (1);
if ((datum = Server_Input.read ()) >= 0 &&
datum != '\n')
{
// Push the byte back onto the stream.
Server_Input.reset ();
--Total_Received;
}
case '\n':
break Line;
default:
line.append ((char)datum);
}
}
if (datum < 0)
{
// EOF
if (line.length () == 0)
throw new EOFException (ID + '\n'
+ "Unexpected server disconnect.");
}
if (Logging)
System.out.println (LOG_INPUT_PREFIX + line);
return line.toString ();
}
/** Add a field String to the HTTP Headers Vector.
The first word of the field String is the header name; the remainder
is the header content (this may be empty). If a header by the same
name already exists in the HTTP Headers Vector, its content is
{@link #Header_Append(String, String) appended} with the new
content.
@param field_string The HTTP header line String.
*/
private void Header_Add
(
String field_string
)
{
if (field_string == null ||
field_string.length () == 0)
return;
// Break the field string into a field name-content vector.
Words
words = new Words (field_string)
.Delimiters (field_string.startsWith ("HTTP") ?
HTTP_VERSION_DELIMITERS : FIELD_CONTENT_DELIMITERS);
Vector
field = words.Split (2);
if (field.size () != 0)
{
if (field.size () == 1)
// Provide empty content.
field.add ("");
if (! Header_Append ((String)field.get (0), (String)field.get (1)))
// New field.
HTTP_Headers.add (field);
}
}
/** Append header content to an existing header.
If a header with the name exists in the HTTP Headers Vector
it's content is appended, after a space character, with the
content String.
@param name The name of a header to have its content
appended.
@param content The content String to be appended.
@return true if a header with the name was found; false otherwise.
*/
private boolean Header_Append
(
String name,
String content
)
{
if (name == null ||
content == null ||
content.length () == 0)
return false;
int
index = Header_Index (name);
if (index < 0)
return false;
Vector
field = (Vector)HTTP_Headers.get (index);
/* N.B.: It is assumed that the field will always have
field name and field content elements,
even if one or both are empty.
*/
field.set (1, (String)field.get (1) + ' ' + content);
return true;
}
/** Get the HTTP Headers Vector index for a named header.
@param name The name of a header.
@return The HTTP Headers Vector index for the named header, or -1
if the header name was not found.
*/
private int Header_Index
(
String name
)
{
if (name != null)
{
int
index = 0,
total = HTTP_Headers.size ();
while (index < total)
{
/* N.B.: It is assumed that the field will always have
a field name element, even if it is empty.
*/
Vector
field = (Vector)HTTP_Headers.get (index);
if (name.equalsIgnoreCase
((String)((Vector)HTTP_Headers.get (index)).get (0)))
return index;
++index;
}
}
return -1;
}
/** Get the header content for a named header.
@param name The name of a header.
@return The content String for the named header, or null if the
header name was not found.
*/
public String Header_Content
(
String name
)
{
String
content = null;
int
index = Header_Index (name);
if (index >= 0)
/* N.B.: It is assumed that the field will always have
field name and field content elements,
even if one or both are empty.
*/
content = (String)((Vector)HTTP_Headers.get (index)).get (1);
return content;
}
/** Get the complete header field for a named header.
The header field is provided in the same syntax as it was
received from the server. However, any header wrapping has been
removed. If multiple headers with the same name were received,
a single header field with all content appended in the order it
was received is provided.
@param name The name of a header.
@return The complete header field String.
*/
public String Header_Field
(
String name
)
{
String
content = Header_Content (name);
if (content != null);
name +=
(name.equalsIgnoreCase ("HTTP") ?
HTTP_VERSION_DELIMITERS.charAt (0) :
FIELD_CONTENT_DELIMITERS.charAt (0)) +
' ' + content;
return name;
}
/** Get a header field value by name.
A header field is divided into value fields by any one of the ':',
';', ',', '&' or whitespace characters. A value field occurs in in
header content as a value name separated from its value by an '='
character.
@param name The name of a header.
@param value_name The name of a content value.
@return The value String. This will be null if the header or value
name is not found.
*/
public String Header_Value
(
String name,
String value_name
)
{
if (value_name == null)
return null;
String
value = null,
content = Header_Content (name);
if (content != null)
{
Vector
values = new Words (content)
.Delimiters (FIELD_CONTENT_DELIMITERS)
.Split ();
for (int index = 0,
total = values.size ();
index < total;
++index)
{
Vector
field_value = new Words ((String)values.get (index))
.Delimiters (VALUE_DELIMITERS)
.Split (2);
if (field_value.size () == 0)
// Empty value!
continue;
String
key = (String)field_value.get (0);
if (value_name.equalsIgnoreCase (key))
{
if (field_value.size () == 1)
// Only a value.
value = key;
else
// key=value.
value = ((String)field_value.get (1)).trim ();
break;
}
}
}
return value;
}
/** Get a header field value by index within the field content.
@param name The name of a header.
@param value_index An index int, starting with zero for the
first value in the content.
@return The value String. This will be null if the header or value
is not found.
@see #Header_Value(String, String)
*/
public String Header_Value
(
String name,
int value_index
)
{
if (value_index < 0)
return null;
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println (">>> HTTP_ImageInputStream.Header_Value: "
+ name + ' ' + value_index);
String
value = null,
content = Header_Content (name);
if (content != null)
{
Vector
values = new Words (content)
.Delimiters (FIELD_CONTENT_DELIMITERS)
.Split ();
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println (" HTTP_ImageInputStream.Header_Value:\n"
+ " values: " + values);
if (values.size () > value_index)
{
values = new Words ((String)values.get (value_index))
.Delimiters (VALUE_DELIMITERS)
.Split (2);
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println
(" value: " + values);
if (values.size () == 0)
// Empty value!
value = "";
else if (values.size () == 1)
// Only a value.
value = (String)values.get (0);
else
// key=value.
value = ((String)values.get (1)).trim ();
}
}
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println (">>> HTTP_ImageInputStream.Header_Value: " + value);
return value;
}
/** Get the HTTP status of the last response from the server.
The HTTP status is expected to be the second field value of the
"HTTP" response header.
@return The HTTP status value. This will be zero if no HTTP status
has yet been found. It will be negative if the expected HTTP
status field does not contain an integer value.
*/
public int Status ()
{
if (HTTP_Status > 0)
return HTTP_Status;
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println (">>> HTTP_ImageInputStream.Status");
String
status_string = Header_Value ("HTTP", 1);
if (status_string != null)
{
try {HTTP_Status = Integer.parseInt (status_string);}
catch (NumberFormatException exception)
{HTTP_Status = -2;}
}
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println
("<<< HTTP_ImageInputStream.Status: " + HTTP_Status);
return HTTP_Status;
}
/** Get the size of the source file.
If the source file size has already been determined the cached value
is returned.
The size of the source file is obtained from the {@link
#Content_Range() "Content-Range"} HTTP response header. If a valid
size value is found the cached value is updated and that value
returned.
@return The size of the source file. This will be {@link #NO_SOURCE_SIZE}
if the size is unknown.
*/
public long Source_Size ()
{
if (Source_Size != NO_SOURCE_SIZE)
return Source_Size;
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println (">>> HTTP_ImageInputStream.Source_Size");
Range
range = Content_Range ();
if (range != null &&
range.Length >= 0)
Source_Size = range.Length;
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println
("<<< HTTP_ImageInputStream.Source_Size: " + Source_Size);
return Source_Size;
}
/** Get the length of server response data content.
The length of the data content is expected to be the first field
of the "Content-Length" HTTP response header.
@return The long value length of the response data content. This
will be -1 if the content length could not be found. It will be
-2 if the expected HTTP header field does not contain an valid
value.
*/
public long Content_Length ()
{
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println (">>> HTTP_ImageInputStream.Content_Length");
long
length = -1;
String
length_string = Header_Value ("Content-Length", 0);
if (length_string != null)
{
try {length = Long.parseLong (length_string);}
catch (NumberFormatException exception)
{length = -2;}
}
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println ("<<< HTTP_ImageInputStream.Content_Length: " + length);
return length;
}
/** Get the Content-Range header values.
The format of the Content-Range header is:
Content-Range: bytes start-end/length
Where
@return A Range containing the Content-Range values, or null
if no Content-Range header could be found. Missing values
in the range are indicated by the value -1.
*/
public Range Content_Range ()
{
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println (">>> HTTP_ImageInputStream.Content_Range");
Range
range = null;
String
range_string = Header_Value ("Content-Range", 1);
Values:
if (range_string != null)
{
range = new Range (-1, -1, -1);
int
first = 0,
last;
// Start
if ((last = range_string.indexOf ('-')) <= 0)
break Values;
try {range.Start = Long.parseLong (range_string.substring (first, last));}
catch (NumberFormatException exception)
{break Values;}
// End
first = ++last;
if ((last = range_string.indexOf ('/')) <= 0)
{
// Try using the remainder of the string.
if ((last = range_string.length ()) == first)
// No remainder.
break Values;
}
try {range.End = Long.parseLong (range_string.substring (first, last));}
catch (NumberFormatException exception)
{break Values;}
// Length
first = ++last;
if (first < range_string.length ())
{
try {range.Length = Long.parseLong (range_string.substring (first));}
catch (NumberFormatException exception) {}
}
}
if ((DEBUG & DEBUG_HEADERS) != 0)
System.out.println ("<<< HTTP_ImageInputStream.Content_Range: " + range);
return range;
}
/** A Range contains Start, End and Length values.
The Length is not necessarily the length between Start and
End. There are no constraints on any of the values.
*/
public class Range
{
public long
Start = 0,
End = 0,
Length = 0;
Range
(
long start,
long end,
long length
)
{
Start = start;
End = end;
Length = length;
}
public String toString ()
{
return Long.toString (Start) + '-' + End + '/' + Length;
}
}
/*==============================================================================
Application main
*/
public static void main
(
String[] args
)
{
if (DEBUG != DEBUG_OFF)
System.out.println
("*** " + ID + " ***");
String
connection_URL = null;
boolean
logging = false;
for (int count = 0;
count < args.length;
count++)
{
if (args[count].length () > 1 &&
args[count].charAt (0) == '-')
{
switch (args[count].charAt (1))
{
case 'L':
case 'l':
logging = true;
break;
case 'H':
case 'h':
default:
Usage ();
}
}
else
{
if (connection_URL != null)
{
System.out.println
("Multiple connection URLs specified -\n"
+" " + connection_URL + " and\n" + args[count]);
Usage ();
}
connection_URL = args[count];
}
}
if (connection_URL == null)
Usage ();
try
{
HTTP_ImageInputStream
source = new HTTP_ImageInputStream (new URL (connection_URL));
source.Logging (logging);
if (DEBUG != DEBUG_OFF)
source.Logging (true);
System.out.println ("Check source status: "
+ source.Check_Source ());
}
catch (Exception exception)
{
System.out.println ("!!! " + exception);
System.exit (1);
}
}
public static void Usage ()
{
System.out.println
(
ID + '\n' +
"Usage: HTTP_ImageInputStream
The conversion algorithm is:
@param image_coordinate The image sample,line coordinate.
@return The world longitude,latitude coordinate. The {@link
Point2D#getX() x} value of the coordinate Point2D is the
longitude; the {@link Point2D#getY() y} value is the latitude.
Values are in degrees within the range 0-360.
*/
public Point2D.Double to_World
(
Point2D image_coordinate
)
throws IllegalArgumentException
{
if (image_coordinate == null)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to project image coordinates to world coordinates\n"
+ "because the image coordinates point is null.");
if ((DEBUG & DEBUG_CONVERTERS) != 0)
System.out.println
(">>> Equirectangular_Projection.to_World: " + image_coordinate);
Point2D.Double
world_coordinate = null;
if (Not_Identity)
{
if ((DEBUG & DEBUG_CONVERTERS) != 0)
{
double
value;
value =
Center_Longitude
+ Sample_to_Projection_X (image_coordinate.getX ())
/ Coefficient_CLR;
System.out.println
(" StrictMath.toDegrees (\n"
+" Center_Longitude " + Center_Longitude + " +\n"
+" Sample_to_Projection_X (" + image_coordinate.getX () + ") "
+ Sample_to_Projection_X (image_coordinate.getX ()) + " /\n"
+" Coefficient_CLR " + Coefficient_CLR + " = " + value + "\n"
+" ) = " + StrictMath.toDegrees (value));
value =
Line_to_Projection_Y (image_coordinate.getY ())
/ Center_Latitude_Radius;
System.out.println
(" StrictMath.toDegrees (\n"
+" Line_to_Projection_Y (" + image_coordinate.getY () + ") "
+ Line_to_Projection_Y (image_coordinate.getY ()) + " /\n"
+" Center_Latitude_Radius " + Center_Latitude_Radius
+ " = " + value + "\n"
+" ) = " + StrictMath.toDegrees (value));
}
world_coordinate = new Point2D.Double
(
StrictMath.toDegrees (
Center_Longitude
+ Sample_to_Projection_X (image_coordinate.getX ())
/ Coefficient_CLR),
StrictMath.toDegrees (
Line_to_Projection_Y (image_coordinate.getY ())
/ Center_Latitude_Radius)
);
}
else
world_coordinate = new Point2D.Double
(image_coordinate.getX (), image_coordinate.getY ());
if ((DEBUG & DEBUG_CONVERTERS) != 0)
System.out.println
("<< Equirectangular_Projection.to_World: " + world_coordinate);
return world_coordinate;
}
/** Get the image sample,line coordinate for a world longitude,latitude
coordinate.
The conversion algorithm is:
@param world_coordinate The world longitude,latitude coordinate.
The {@link Point2D#getX() x} value of the coordinate Point2D is
the longitude; the {@link Point2D#getY() y} value is the
latitude. Values are in degrees.
@return The image sample,line coordinate.
*/
public Point to_Image
(
Point2D world_coordinate
)
throws IllegalArgumentException
{
if (world_coordinate == null)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to project world coordinates to image coordinates\n"
+ "because the world coordinates point is null.");
Point
image_coordinate = null;
if (Not_Identity)
image_coordinate = new Point
(
(int)(Projection_X_to_Sample (Coefficient_CLR
* (StrictMath.toRadians (world_coordinate.getX ())
- Center_Longitude))
+ 0.5), // Round to nearest pixel.
(int)(Projection_Y_to_Line (Center_Latitude_Radius
* StrictMath.toRadians (world_coordinate.getY ()))
+ 0.5) // Round to nearest pixel.
);
else
image_coordinate = new Point
((int)world_coordinate.getX (), (int)world_coordinate.getY ());
return image_coordinate;
}
}
pirl-2.3.8/PIRL/Image_Tools/Projection.java 0000644 0001750 0001750 00000105675 12023520230 020276 0 ustar mathieu mathieu /* Projection
PIRL CVS ID: Projection.java,v 1.8 2012/09/11 02:23:20 castalia Exp
Copyright (C) 2007-2012 Arizona Board of Regents on behalf of the
Planetary Image Research Laboratory, Lunar and Planetary Laboratory at
the University of Arizona.
This file is part of the PIRL Java Packages.
The PIRL Java Packages are free software; you can redistribute them
and/or modify them under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
The PIRL Java Packages are distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see
Spatial projections are used in many contexts. The typical example is
when a camera image of curved surface is to be mapped as if the
surface were flat. The commonly known Mercator projection of a map of
the Earth is such a projection. There are many map projections. See
Snyder, John P., "Map Projections - A Working Manual", U.S Geological
Survey Professional Paper 1395, 1987 for a discussion of the map
projection algorithm used in these classes.
The core projection characteristic is an algorithm that maps
coordinates from one coordinate system to another. The specific
projection algorithms used - the implementation of a set of equations
- will, of course, vary from one type of projection to another to
achieve the desired mapping effect. In addition, the choice of
projection is likey to depend on the range of coordinate values to be
mapped - projections are likely to have increasing visual distortion
effects as boundary conditions are approached - or the accuracy to be
achieved - the implementing equations are like to make various
simplifying assumptions. Nevertheless, all projections are expected
to map coordinates between image and world coordinate systems. The
former is in image pixel units of sample - horizontal distance from
the left-most pixel - and and line - vertical distance from the
top-most line - of a rectangular array of pixels. The latter is
typically in planetary longitude - angular angular distance about the
center of the planet relative to a zero-reference longitude - and
latitude - angular angular distance about the center of the planet
relative to the equator - usually measured in decimal degrees.
However, other "world" coordinate systems are quite possible. In
order to accommodate images of arbitrary location, an intermediate
projeciton coordinate system is typically used by the projection
equations, with a simple translational equation used to map between
the projection coordinate system and the location of the image raster
in that system.
A specific projection, implemented as a subclass of Projection, will
require various parameters need by the projection equations. These
are supplied by a PVL Parameter Aggregate. Because this Projection
implementation assumes that planetary projections are to be
implemented by subclasses, the Parameter group used to construct a
Projection collects the common set of parameter values required by
the specific projection algorithms. If all the required parameters
are not provided the default identity projection - in which
coordinate values are not changed - is used.
@author Bradford Castalia UA/PIRL
@version 1.8
*/
public class Projection
{
/** Class name and version identification.
*/
public static final String
ID = "PIRL.Image_Tools.Projection (1.8 2012/09/11 02:23:20)";
//! The projection name (override in subclass).
private static final String
PROJECTION_NAME = "Idenitity";
public static final String
PROJECTION_PARAMETER_NAME = "MAP_PROJECTION_TYPE",
EQUIRECTANGULAR_PROJECTION_NAME = "EQUIRECTANGULAR",
POLAR_STEREOGRAPHIC_PROJECTION_NAME = "POLAR STEREOGRAPHIC",
POLARSTEREOGRAPHIC_PROJECTION_NAME = "POLARSTEREOGRAPHIC",
PROJECTION_LATITUDE_PARAMETER_NAME = "PROJECTION_LATITUDE_TYPE",
PLANETOCENTRIC_PROJECTION_NAME = "PLANETOCENTRIC",
EQUITORIAL_RADIUS_PARAMETER_NAME = "A_AXIS_RADIUS",
POLAR_RADIUS_PARAMETER_NAME = "C_AXIS_RADIUS",
METERS_PER_PIXEL_PARAMETER_NAME = "MAP_SCALE",
POSITIVE_LONGITUDE_PARAMETER_NAME = "POSITIVE_LONGITUDE_DIRECTION",
POSITIVE_LONGITUDE_EAST_NAME = "EAST",
POSITIVE_LONGITUDE_WEST_NAME = "WEST",
CENTER_LATITUDE_PARAMETER_NAME = "CENTER_LATITUDE",
CENTER_LONGITUDE_PARAMETER_NAME = "CENTER_LONGITUDE",
SAMPLE_OFFSET_PARAMETER_NAME = "SAMPLE_PROJECTION_OFFSET",
LINE_OFFSET_PARAMETER_NAME = "LINE_PROJECTION_OFFSET",
NOT_APPLICABLE_CONSTANT_PARAMETER_NAME = "NOT_APPLICABLE_CONSTANT";
protected boolean
Not_Identity = false,
Positive_West, // POSITIVE_LONGITUDE_DIRECTION
Planetocentric; // PROJECTION_LATITUDE_TYPE
public static final double
DEFAULT_NA = -9998.0;
protected double
Meters_per_Pixel = 0.0, // MAP_SCALE
Equitorial_Radius = 0.0, // A_AXIS_RADIUS
@param parameters The Parameter Aggregate containing (at least) the
minimally required parameter values. If all required parameters
are not provided - including if the argument is null - the {@link
#Is_Identity() identity projection flag} is set.
@throws PVL_Exception If there is a problem reading the parameters
or a parameter is found to have an invalid value.
*/
public Projection
(
Parameter parameters
)
throws PVL_Exception
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> Projection: " + parameters);
if (parameters == null)
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< Projection");
return;
}
try {NA =
Find_Parameter (parameters, NOT_APPLICABLE_CONSTANT_PARAMETER_NAME)
.Value ().double_Data ();}
catch (Exception exception) {/* Use the default */}
try
{
Meters_per_Pixel =
Find_Parameter (parameters, METERS_PER_PIXEL_PARAMETER_NAME)
.Value ().double_Data ();
if (Meters_per_Pixel <= 0.0 ||
Meters_per_Pixel == NA)
throw new PVL_Exception (ID + '\n'
+ "Invalid " + METERS_PER_PIXEL_PARAMETER_NAME + " value: "
+ Meters_per_Pixel + '\n'
+ "The value must be a valid non-zero positive.");
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Meters_per_Pixel = " + Meters_per_Pixel);
Equitorial_Radius =
Find_Parameter (parameters, EQUITORIAL_RADIUS_PARAMETER_NAME)
.Value ().double_Data () * 1000.0;
if (Equitorial_Radius <= 0.0 ||
Equitorial_Radius == NA)
throw new PVL_Exception (ID + '\n'
+ "Invalid " + EQUITORIAL_RADIUS_PARAMETER_NAME + " value: "
+ Equitorial_Radius + '\n'
+ "The value must be a valid non-zero positive.");
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Equitorial_Radius = " + Equitorial_Radius);
Polar_Radius =
Find_Parameter (parameters, POLAR_RADIUS_PARAMETER_NAME)
.Value ().double_Data () * 1000.0;
if (Polar_Radius <= 0.0 ||
Polar_Radius == NA)
throw new PVL_Exception (ID + '\n'
+ "Invalid " + POLAR_RADIUS_PARAMETER_NAME + " value: "
+ Polar_Radius + '\n'
+ "The value must be a valid non-zero positive.");
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Polar_Radius = " + Polar_Radius);
// Planetocentric_to_Planetographic conversion coefficient.
Coefficient_PC_to_PG =
(Equitorial_Radius / Polar_Radius) * (Equitorial_Radius / Polar_Radius);
// Planetographic_to_Planetocentric conversion coefficient.
Coefficient_PG_to_PC =
(Polar_Radius / Equitorial_Radius) * (Polar_Radius / Equitorial_Radius);
Eccentricity = Eccentricity (Polar_Radius, Equitorial_Radius);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Eccentricity = " + Eccentricity);
String
string =
Find_Parameter (parameters, POSITIVE_LONGITUDE_PARAMETER_NAME)
.Value ().String_Data ();
if (string.equalsIgnoreCase (POSITIVE_LONGITUDE_WEST_NAME))
Positive_West = true;
else
if (string.equalsIgnoreCase (POSITIVE_LONGITUDE_EAST_NAME))
Positive_West = false;
else
throw new PVL_Exception (ID + '\n'
+ "Invalid " + POSITIVE_LONGITUDE_PARAMETER_NAME + " value: "
+ string + '\n'
+ "The value must be \"" + POSITIVE_LONGITUDE_WEST_NAME
+ "\" or \"" + POSITIVE_LONGITUDE_EAST_NAME + "\".");
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Positive_West = " + Positive_West);
Sample_Offset =
Find_Parameter (parameters, SAMPLE_OFFSET_PARAMETER_NAME)
.Value ().double_Data ();
if (Sample_Offset == NA)
throw new PVL_Exception (ID + '\n'
+ "Invalid " + SAMPLE_OFFSET_PARAMETER_NAME + " value: "
+ Sample_Offset);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Sample_Offset = " + Sample_Offset);
Line_Offset =
Find_Parameter (parameters, LINE_OFFSET_PARAMETER_NAME)
.Value ().double_Data ();
if (Line_Offset == NA)
throw new PVL_Exception (ID + '\n'
+ "Invalid " + LINE_OFFSET_PARAMETER_NAME + " value: "
+ Line_Offset);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Line_Offset = " + Line_Offset);
try {Planetocentric =
Find_Parameter (parameters, PROJECTION_LATITUDE_PARAMETER_NAME)
.Value ().String_Data ()
.equalsIgnoreCase (PLANETOCENTRIC_PROJECTION_NAME);}
catch (NoSuchElementException exception) {/* false */}
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Planetocentric = " + Planetocentric);
Center_Longitude =
Find_Parameter (parameters, CENTER_LONGITUDE_PARAMETER_NAME)
.Value ().double_Data ();
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Center_Longitude = " + Center_Longitude);
if (Center_Longitude == NA)
throw new PVL_Exception (ID + '\n'
+ "Invalid " + CENTER_LONGITUDE_PARAMETER_NAME + " value: "
+ Center_Longitude);
Center_Longitude = StrictMath.toRadians (Center_Longitude);
if (Positive_West)
Center_Longitude *= -1.0;
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" " + Center_Longitude);
Center_Latitude =
Find_Parameter (parameters, CENTER_LATITUDE_PARAMETER_NAME)
.Value ().double_Data ();
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Center_Latitude = " + Center_Latitude);
if (Center_Latitude == NA)
throw new PVL_Exception (ID + '\n'
+ "Invalid " + CENTER_LATITUDE_PARAMETER_NAME + " value: "
+ Center_Latitude);
Center_Latitude = StrictMath.toRadians (Center_Latitude);
if (Planetocentric)
Center_Latitude = Planetocentric_to_Planetographic (Center_Latitude);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" " + Center_Latitude);
Not_Identity = true;
}
catch (NoSuchElementException exception)
{/* Take this exception to mean that the image is not projected. */}
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< Projection");
}
/** Constructs a default identity Projection.
The {@link #Is_Identity() identity projection flag} is set.
*/
public Projection ()
{}
/** Creates a Projection object that uses an appropriate specific
Projection subclass projection implementation.
The choice of specific projection implementation is based on the
value of the Parameter having the {@link #PROJECTION_PARAMETER_NAME}.
This name is used to assemble a {@link #Projection_Class_Name(String)
projection specific class name} to be loaded. Once loaded, a new
instance is constructed using the parameters argument.
As a special case, if the projection name is {@link
#POLAR_STEREOGRAPHIC_PROJECTION_NAME} the "_Spherical" suffix is
appended if {@link #Use_Spherical(boolean)} is enabled so the faster but
slightly less accurate spherical form of the projection will be used;
otherwise the "_Elliptical" suffix is appended so the elliptical form
will be used. Also, if the name is {@link
#POLARSTEREOGRAPHIC_PROJECTION_NAME} it will be converted to the
{@link #POLAR_STEREOGRAPHIC_PROJECTION_NAME}
@param parameters The Parameter Aggregate containing the projection
definition parameter values. These parameters will be passed to
the specific projection class to be constructed. If null, not an
Aggregate Parameter, or there is no {@link
#PROJECTION_PARAMETER_NAME} parameter a default Projection is
constructed which will have the {@link #Is_Identity() identity
projection flag} set.
@return A Projection or Projection subclass, Object.
@throws PVL_Exception If there is a problem reading the parameters
or a parameter is found to have an invalid value.
@throws NoSuchElementException If any required parameter was missing
from the provided parameters.
@throws UnsupportedOperationException If the expected Projection
subclass could not be loaded or instantiated.
@throws Throwable If the constructor of the loaded projection class
throws an unexpected exception.
@see Equirectangular_Projection
@see Polar_Stereographic_Elliptical_Projection
@see Polar_Stereographic_Spherical_Projection
*/
public static Projection Create
(
Parameter parameters
)
throws
PVL_Exception,
NoSuchElementException,
UnsupportedOperationException,
Throwable
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(">>> Projection.Create: " + parameters);
Projection
projection = null;
if (parameters == null ||
! parameters.Is_Aggregate ())
// Identity Projection when no parameters.
projection = new Projection ();
String
projection_name = null;
try
{
Parameter
projection_parameter
= Find_Parameter (parameters, PROJECTION_PARAMETER_NAME);
try {projection_name = projection_parameter.Value ().String_Data ();}
catch (PVL_Exception except) {}
}
catch (NoSuchElementException exception) {}
if (projection_name == null)
// Identity Projection when no valid projection name parameter.
projection = new Projection ();
else
{
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" " + PROJECTION_PARAMETER_NAME + " = " + projection_name);
if (projection_name.equalsIgnoreCase (POLAR_STEREOGRAPHIC_PROJECTION_NAME) ||
projection_name.equalsIgnoreCase (POLARSTEREOGRAPHIC_PROJECTION_NAME))
{
if (Use_Spherical)
projection_name += "_spherical";
else
projection_name += "_elliptical";
}
projection_name = Projection_Class_Name (projection_name);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Projection class name: " + projection_name);
Class
projection_class = null;
try {projection_class = Class.forName (projection_name);}
catch (ClassNotFoundException exception)
{
try {projection_class =
Class.forName ("PIRL.Image_Tools." + projection_name);}
catch (ClassNotFoundException except)
{
throw new UnsupportedOperationException (ID + '\n'
+ "Unable to find the \"" + projection_name + "\" class.");
}
}
try
{
Class[]
parameter_class = new Class[1];
parameter_class[0] = parameters.getClass ();
Constructor
projection_constructor =
projection_class.getConstructor (parameter_class);
Object
argument[] = new Object[1];
argument[0] = parameters;
projection = (Projection)projection_constructor.newInstance (argument);
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
(" Projection: " + projection);
}
catch (InvocationTargetException exception)
{
Throwable
throwable = exception.getCause ();
if (throwable != null)
throw throwable;
throw exception;
}
catch (NoSuchElementException exception)
{throw exception;}
catch (Exception exception)
{
UnsupportedOperationException
unsupported = new UnsupportedOperationException (ID + '\n'
+ "Unable to load the \""
+ projection_name + "\" projection class.");
unsupported.initCause (exception);
}
}
if ((DEBUG & DEBUG_CONSTRUCTORS) != 0)
System.out.println
("<<< Projection.Create: " + parameters);
return projection;
}
/*==============================================================================
Accessors
*/
public String Name ()
{return PROJECTION_NAME;}
public boolean Is_Identity ()
{return ! Not_Identity;}
public double Resolution ()
{return Meters_per_Pixel;}
public double Equitorial_Radius ()
{return Equitorial_Radius;}
public double Polar_Radius ()
{return Polar_Radius;}
public double Eccentricity ()
{return Eccentricity;}
public double Sample_Offset ()
{return Sample_Offset;}
public double Line_Offset ()
{return Line_Offset;}
public boolean Positive_West ()
{return Positive_West;}
public Projection Positive_West
(
boolean positive_west
)
{Positive_West = positive_west; return this;}
public boolean Planetocentric ()
{return Planetocentric;}
public Projection Planetocentric
(
boolean planetocentric
)
{Planetocentric = planetocentric; return this;}
public double Center_Latitude ()
{return Center_Latitude;}
public double Center_Longitude ()
{return Center_Longitude;}
public static boolean Use_Spherical
(
boolean enabled
)
{
boolean
previous_state = Use_Spherical;
Use_Spherical = enabled;
return previous_state;
}
/*==============================================================================
Converters
*/
/** Get the world longitude,latitude coordinate for an image sample.line
coordinate.
This method simply returns a copy of the coordinate argument. A
projection specific subclass will override this method.
@param image_coordinate The image sample,line coordinate.
@return A copy of the image_coordinate.
*/
public Point2D.Double to_World
(
Point2D image_coordinate
)
{
if (image_coordinate == null)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to project world coordinates to image coordinates\n"
+ "because the world coordinates point is null.");
return new Point2D.Double (image_coordinate.getX (), image_coordinate.getY ());
}
/** Get the image sample,line coordinate for a world longitude,latitude
coordinate.
This method simply returns a copy of the coordinate argument. A
projection specific subclass will override this method.
@param world_coordinate The world longitude,latitude coordinate.
@return A copy of the world_coordinate.
*/
public Point to_Image
(
Point2D world_coordinate
)
{
if (world_coordinate == null)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to project image coordinates to world coordinates\n"
+ "because the image coordinates point is null.");
return new Point ((int)world_coordinate.getX (), (int)world_coordinate.getY ());
}
/** Converts an angle in decimal degrees, to a degrees, minutes, seconds
representation.
The format of the degrees, minutes, seconds String representation is:
@param angle The angle in degrees to be represented.
@return The String representation.
*/
public static String Degrees_Minutes_Seconds
(
double angle
)
{
int
degrees = (int)angle;
double
fraction = Math.abs (angle - degrees) * 60.0;
int
minutes = (int)fraction;
fraction = (fraction - minutes) * 60.0;
int
seconds = (int)fraction;
int
msecs = (int)((fraction - seconds) * 1000.0 + 0.5);
if (msecs >= 1000)
{
msecs -= 1000;
seconds++;
}
if (seconds >= 60)
{
seconds -= 60;
minutes++;
}
if (minutes >= 60)
{
minutes -= 60;
degrees++;
}
return
((degrees < 10) ? " " :
((degrees < 100) ? " " : ""))
+ degrees + "d "
+
((minutes < 10) ? " " : "")
+ minutes + "m "
+
((seconds < 10) ? " " : "")
+ seconds + "."
+
((msecs < 10) ? "00" :
((msecs < 100) ? "0" : ""))
+ msecs + "s";
}
/** Converts an angle in decimal degrees, to an hours, minutes, seconds
representation.
The format of the hours, minutes, seconds String representation is:
@param angle The angle in degrees to be represented.
@return The String representation.
*/
public static String Hours_Minutes_Seconds
(
double angle
)
{
angle = To_360 (angle) / 15.0;
int
hours = (int)angle;
double
fraction = Math.abs (angle - hours) * 60.0;
int
minutes = (int)fraction;
fraction = (fraction - minutes) * 60.0;
int
seconds = (int)fraction;
int
msecs = (int)((fraction - seconds) * 1000.0 + 0.5);
if (msecs >= 1000)
{
msecs -= 1000;
seconds++;
}
if (seconds >= 60)
{
seconds -= 60;
minutes++;
}
if (minutes >= 60)
{
minutes -= 60;
hours++;
}
return
((hours < 10) ? " " : "")
+ hours + "h "
+
((minutes < 10) ? " " : "")
+ minutes + "m "
+
((seconds < 10) ? " " : "")
+ seconds + "."
+
((msecs < 10) ? "00" :
((msecs < 100) ? "0" : ""))
+ msecs + "s";
}
public static double Decimal_Degrees
(
String parts
)
throws IllegalArgumentException, NumberFormatException
{
double
degrees;
Words
words = new Words (parts);
String
part = words.Next_Word ();
int
index = part.length () - 1;
if (index < 0)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to convert to decimal degrees: \"" + parts + '"');
char
character = part.charAt (index);
if (character == 'd' ||
character == 'D')
{
// Degrees.
try {degrees = Integer.parseInt (part.substring (0, index));}
catch (NumberFormatException exception)
{
throw new NumberFormatException (ID + '\n'
+ "Unable to convert to decimal degrees: \"" + parts + "\"\n"
+ "Degrees (the first value) must be an integer.");
}
}
else
{
// Hours.
if (character == 'h' ||
character == 'H')
part = part.substring (0, index);
try {degrees = Integer.parseInt (part) * 15;} // Convert to degrees.
catch (NumberFormatException exception)
{
throw new NumberFormatException (ID + '\n'
+ "Unable to convert to decimal degrees: \"" + parts + "\"\n"
+ "Hours (the first value) must be an integer.");
}
}
degrees = To_360 (degrees);
part = words.Next_Word ();
if ((index = part.length () - 1) >= 0)
{
// Minutes.
character = part.charAt (index);
if (character == 'm' ||
character == 'M')
part = part.substring (0, index);
int
minutes;
try {minutes = Integer.parseInt (part);}
catch (NumberFormatException exception)
{
throw new NumberFormatException (ID + '\n'
+ "Unable to convert to decimal degrees: \"" + parts + "\"\n"
+ "Minutes (the second value) must be an integer.");
}
if (minutes < 0 ||
minutes > 59)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to convert to decimal degrees: \"" + parts + "\"\n"
+ "Minutes (the second value) must be in the range [0-60).");
degrees += (double)minutes * (15.0 / 60.0); // Convert to degrees.
part = words.Next_Word ();
if ((index = part.length () - 1) >= 0)
{
// Seconds.
character = part.charAt (index);
if (character == 's' ||
character == 'S')
part = part.substring (0, index);
double
seconds;
try {seconds = Double.parseDouble (part);}
catch (NumberFormatException exception)
{
throw new NumberFormatException (ID + '\n'
+ "Unable to convert to decimal degrees: \"" + parts + "\"\n"
+ "Seconds (the third value) must be a real number.");
}
if (seconds < 0.0 ||
seconds >= 60.0)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to convert to decimal degrees: \"" + parts + "\"\n"
+ "Seconds (the third value) must be in the range [0-60).");
degrees += (double)seconds * (15.0 / 3600.0); // Convert to degrees.
part = words.Next_Word ();
if (part.length () != 0)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to convert to decimal degrees: \"" + parts + "\"\n"
+ "Seconds (the third value) should be the last part.");
}
}
return degrees;
}
/** Convert planetocentric latitude to planetographic latitude.
@param latitude The latitude, in radians, to convert.
@return The converted latitude value.
*/
public double Planetocentric_to_Planetographic
(
double latitude
)
{
if (Not_Identity &&
Math.abs (latitude) < PI_OVER_2)
latitude =
StrictMath.atan (StrictMath.tan (latitude) * Coefficient_PC_to_PG);
return latitude;
}
/** Convert planetographic latitude to planetocentric latitude.
@param latitude The latitude, in radians, to convert.
@return The converted latitude value.
*/
public double Planetographic_to_Planetocentric
(
double latitude
)
{
if (Not_Identity &&
Math.abs (latitude) < PI_OVER_2)
latitude =
StrictMath.atan (StrictMath.tan (latitude) * Coefficient_PG_to_PC);
return latitude;
}
protected double Projection_X_to_Sample
(
double projection_x
)
{return (projection_x / Meters_per_Pixel) + Sample_Offset;}
protected double Projection_Y_to_Line
(
double projection_y
)
{return (projection_y / Meters_per_Pixel) - Line_Offset;}
protected double Sample_to_Projection_X
(
double sample
)
{return (sample - Sample_Offset) * Meters_per_Pixel;}
protected double Line_to_Projection_Y
(
double line
)
{return (-Line_Offset - line) * Meters_per_Pixel;}
/*==============================================================================
Derived values
*/
/** Calculate the planet eccentricity.
@param equitorial_radius The planet equitorial radius.
@param polar_radius The planet polar radius.
@return The planet eccentricity.
*/
public static double Eccentricity
(
double polar_radius,
double equitorial_radius
)
{
return
StrictMath.sqrt (1.0 -
((polar_radius * polar_radius) /
(equitorial_radius * equitorial_radius)));
}
/** Calculate the radius of the planet at some latitude.
@param latitude The latitude, in radians, at which the local
radius is to be calculated.
@return The radius of the planet at the specified latitude.
*/
public double Local_Radius
(
double latitude
)
{
double
radius = 0.0;
if (Not_Identity)
{
if (latitude == PI_OVER_2)
radius = Polar_Radius;
else
if (latitude == 0.0)
radius = Equitorial_Radius;
else
{
double
coefficient_e = Equitorial_Radius * StrictMath.sin (latitude),
coefficient_p = Polar_Radius * StrictMath.cos (latitude);
radius = Equitorial_Radius * Polar_Radius / StrictMath.sqrt
((coefficient_p * coefficient_p) + (coefficient_e * coefficient_e));
}
}
return radius;
}
/** Ensure that a longitude value is in the range 0 to 360 degrees.
A negative longitude value is repeatedly increased by 360 until
it is no longer negative. A longitude value greater than or equal to 360
is repeatedly decreased by 360 until it is less than 360.
@param longitude The longitude value to map to the 0 to 360 degree
domain.
@return The longitude value in the 0-360 degree domain.
*/
public static double To_360
(
double longitude
)
{
while (longitude < 0.0) longitude += 360.0;
while (longitude >= 360.0) longitude -= 360.0;
return longitude;
}
/** Ensure that a longitude value is in the range -180 to 180 degrees.
A longitude value less than -180 is repeatedly increased by 360 until
it is greater than or equal to -180. A longitude value greater than
or equal to 180 is repeatedly decreased by 360 until it is less than
180.
@param longitude The longitude value to map to the -180 to 180
degree domain.
@return The longitude value in the -180 to 180 degree domain.
*/
public static double To_180
(
double longitude
)
{
while (longitude < -180.0) longitude += 360.0;
while (longitude >= 180.0) longitude -= 360.0;
return longitude;
}
/*==============================================================================
Helpers
*/
/** Produce a class name for a projection name.
The projection name is first trimmed of leading and trailing
whitespace and all characters are set to lowercase. If the result
starts with "polar" but is not followed by a space (' ') or underbar
('_') character an underbar is inserted following the "polar" prefix.
Then any remaining space characters are changed to '_' characters.
The first character and every character following an underbar
character is set to uppercase. Finally the "_Projection" String is
appended.
@param projection_name The projection name String.
@return The class name String.
*/
public static String Projection_Class_Name
(
String projection_name
)
{
if (projection_name == null)
return null;
StringBuffer
class_name = new StringBuffer
(projection_name = projection_name.trim ().toLowerCase ());
// Special case.
if (projection_name.startsWith ("polar") &&
class_name.length () > 5 &&
class_name.charAt (5) != ' ' &&
class_name.charAt (5) != '_')
class_name.insert (5, "_");
if (class_name.length () != 0)
{
class_name.setCharAt (0, Character.toUpperCase (class_name.charAt (0)));
int
index = 0;
while ((index = class_name.indexOf (" ", index)) > 0)
class_name.setCharAt (index++, '_');
index = 0;
while ((index = class_name.indexOf ("_", index) + 1) > 0)
class_name.setCharAt (index,
Character.toUpperCase (class_name.charAt (index)));
class_name.append ("_Projection");
}
return class_name.toString ();
}
/** Find a named parameter in PDS label parameters.
@param label The PDS label parameters.
@param name The name of the parameter to find.
@return The Parameter that was found.
@throws NoSuchElementException If the parameter was not found.
*/
protected static Parameter Find_Parameter
(
Parameter label,
String name
)
throws NoSuchElementException
{
Parameter
parameter = label.Find (name);
if (parameter == null)
throw new NoSuchElementException (ID + '\n'
+ "The required \"" + name
+ "\" parameter was not found in the PDS label.");
return parameter;
}
/*==============================================================================
main
*/
public static void main
(
String[] args
)
{
System.out.println (ID);
if (args.length == 0)
Usage ();
Parameter
parameters = null;
boolean
image_coordinates = false,
spherical = false;
Point2D.Double
coordinate = null;
int
index;
String
number;
for (int
count = 0;
count < args.length;
count++)
{
if (args[count].length () == 0)
continue;
if (args[count].charAt (0) == '-' &&
args[count].length () > 1)
{
switch (args[count].charAt (1))
{
case 'A':
case 'a':
if ((count + 1) == args.length)
Usage ();
double
angle = 0;
try {angle = Double.parseDouble (args[++count]);}
catch (NumberFormatException exception)
{
try {angle = Decimal_Degrees (args[count]);}
catch (Exception except)
{
System.out.println
("Not a valid angle: " + args[count] + '\n'
+ except.getMessage ());
Usage ();
}
System.out.println
("Angle = " + args[count]);
break;
}
System.out.println
("Angle = " + angle + '\n'
+" " + Projection.Hours_Minutes_Seconds (angle) + '\n'
+" " + Projection.Degrees_Minutes_Seconds (angle));
break;
case 'S':
case 's':
spherical = true;
break;
case 'I':
case 'i':
image_coordinates = true;
case 'W':
case 'w':
if ((count + 1) == args.length ||
coordinate != null)
Usage ();
coordinate = Coordinate (args[++count]);
break;
default:
System.out.println ("Unknown option: " + args[count]);
Usage ();
}
}
else
{
if (parameters != null)
Usage ();
try {parameters =
new Parameter (new Parser (Streams.Get_Stream (args[count])));}
catch (PVL_Exception exception)
{
System.out.println
("Unable to read PVL source: " + args[count] + '\n'
+ exception.getMessage ());
System.exit (2);
}
}
}
if (parameters != null ||
coordinate != null)
{
if (parameters == null ||
coordinate == null)
Usage ();
try
{
Projection.Use_Spherical (spherical);
Projection
projection = Projection.Create (parameters);
if (image_coordinates)
System.out.println
("Image coordinate: " + coordinate + '\n'
+"World coordinate: " + projection.to_World (coordinate));
else
System.out.println
("World coordinate: " + coordinate + '\n'
+"Image coordinate: " + projection.to_Image (coordinate));
}
catch (Throwable exception)
{
exception.printStackTrace ();
System.exit (3);
}
}
System.exit (0);
}
private static Point2D.Double Coordinate
(
String coordinate
)
{
int
index = coordinate.indexOf (',');
if (index < 0)
Usage ();
Point2D.Double
point = null;
try
{
point = new Point2D.Double
(
Double.parseDouble (coordinate.substring (0, index)),
Double.parseDouble (coordinate.substring (index + 1))
);
}
catch (NumberFormatException exception)
{
System.out.println
("Not a valid coordinate: " + coordinate);
Usage ();
}
return point;
}
public static void Usage ()
{
System.out.println
("Usage: Projection"
+ " [-Angle
The conversion algorithm is:
@param image_coordinate The image sample,line coordinate.
@return The world longitude,latitude coordinate. The {@link
Point2D#getX() x} value of the coordinate Point2D is the
longitude; the {@link Point2D#getY() y} value is the latitude.
Values are in degrees within the range 0-360.
*/
public Point2D.Double to_World
(
Point2D image_coordinate
)
throws IllegalArgumentException, ArithmeticException
{
if ((DEBUG & DEBUG_CONVERTERS) != 0)
System.out.println
(">>> Polar_Stereographic_Elliptical_Projection.to_World: "
+ image_coordinate);
if (image_coordinate == null)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to project image coordinates ("
+ (int)image_coordinate.getX () + ','
+ (int)image_coordinate.getX () + ") to world coordinates\n"
+ "because the image coordinates point is null.");
Point2D.Double
world_coordinate = null;
if (Not_Identity)
{
double
x = Center_Latitude_Sign
* Sample_to_Projection_X (image_coordinate.getX ()),
y = Center_Latitude_Sign
* Line_to_Projection_Y (image_coordinate.getY ()),
distance = StrictMath.sqrt ((x * x) + (y * y)),
coefficient_t = distance * Distance_Coefficient;
// Latitude.
double
latitude = Center_Latitude_Sign * Coefficient_Phi2 (coefficient_t);
if ((DEBUG & DEBUG_CONVERTERS) != 0)
System.out.println
(" Center_Latitude_Sign = " + Center_Latitude_Sign + '\n'
+" x = " + x + '\n'
+" y = " + y + '\n'
+" distance = " + distance + '\n'
+" Distance_Coefficient = " + Distance_Coefficient + '\n'
+" coefficient_t = " + coefficient_t + '\n'
+" Coefficient_Phi2 = " + Coefficient_Phi2 (coefficient_t) + '\n'
+" latitude = " + latitude);
if (Math.abs (latitude) > PI_OVER_2)
throw new ArithmeticException (ID + '\n'
+ "Projection of image coordinates ("
+ (int)image_coordinate.getX () + ','
+ (int)image_coordinate.getX () + ") to world coordinates\n"
+ "resulted in an invalid latitude of "
+ Math.toDegrees (latitude) + " degrees.");
if (Planetocentric)
latitude = Planetographic_to_Planetocentric (latitude);
latitude = StrictMath.toDegrees (latitude);
if ((DEBUG & DEBUG_CONVERTERS) != 0)
System.out.println
(" latitude = " + latitude);
// Longitude.
double
longitude = ((distance == 0.0) ?
(Center_Latitude_Sign * Center_Longitude) :
(Center_Latitude_Sign * StrictMath.atan2 (x, -y)
+ Center_Longitude));
if ((DEBUG & DEBUG_CONVERTERS) != 0)
System.out.println ('\n'
+" Center_Longitude = " + Center_Longitude + '\n'
+ ((distance == 0.0) ? ""
: (" StrictMath.atan2 (x, -y) = "
+ StrictMath.atan2 (x, -y) + '\n'))
+" longitude = " + longitude);
if (Positive_West)
longitude *= -1.0;
longitude = To_360 (StrictMath.toDegrees (longitude));
if ((DEBUG & DEBUG_CONVERTERS) != 0)
System.out.println
(" longitude = " + longitude);
world_coordinate = new Point2D.Double (longitude, latitude);
}
else
world_coordinate = new Point2D.Double
(image_coordinate.getX (), image_coordinate.getY ());
if ((DEBUG & DEBUG_CONVERTERS) != 0)
System.out.println
("<<< Polar_Stereographic_Elliptical_Projection.to_World: "
+ world_coordinate);
return world_coordinate;
}
/** Get the image sample,line coordinate for a world longitude,latitude
coordinate.
The conversion algorithm is:
@param world_coordinate The world longitude,latitude coordinate.
The {@link Point2D#getX() x} value of the coordinate Point2D is
the longitude; the {@link Point2D#getY() y} value is the
latitude. Values are in degrees.
@return The image sample,line coordinate.
*/
public Point to_Image
(
Point2D world_coordinate
)
throws IllegalArgumentException
{
if ((DEBUG & DEBUG_CONVERTERS) != 0)
System.out.println
(">>> Polar_Stereographic_Elliptical_Projection.to_Image: "
+ world_coordinate);
if (world_coordinate == null)
throw new IllegalArgumentException (ID + '\n'
+ "Unable to project world coordinates to image coordinates\n"
+ "because the world coordinates point is null.");
Point
image_coordinate = null;
if (Not_Identity)
{
double
longitude = StrictMath.toRadians (world_coordinate.getX ()),
latitude = StrictMath.toRadians (world_coordinate.getY ());
if (Planetocentric)
latitude = Planetocentric_to_Planetographic (latitude);
if (Positive_West)
longitude *= -1.0;
double
lambda = Center_Latitude_Sign * (longitude - Center_Longitude),
distance = Coefficient_T (latitude) / Distance_Coefficient;
image_coordinate = new Point
(
(int)(Projection_X_to_Sample (
Center_Latitude_Sign * distance * StrictMath.sin (lambda))
+ 0.5), // Round to nearest pixel.
(int)(Projection_Y_to_Line (
-Center_Latitude_Sign * distance * StrictMath.cos (lambda))
+ 0.5) // Round to nearest pixel.
);
}
else
image_coordinate = new Point
((int)image_coordinate.getX (), (int)image_coordinate.getY ());
if ((DEBUG & DEBUG_CONVERTERS) != 0)
System.out.println
("<<< Polar_Stereographic_Elliptical_Projection.to_Image: "
+ image_coordinate);
return image_coordinate;
}
/*==============================================================================
Derived values
*/
private double Coefficient_T
(
double latitude
)
{
if ((PI_OVER_2 - Math.abs (latitude)) < DBL_EPSILON)
return 0.0;
latitude *= Center_Latitude_Sign;
double
e_sin_lat = Eccentricity * StrictMath.sin (latitude);
return
StrictMath.tan (0.5 * (PI_OVER_2 - latitude)) /
StrictMath.pow ((1.0 - e_sin_lat) / (1.0 + e_sin_lat), E_over_2);
}
private double Coefficient_Phi2
(
double coefficient_t
)
throws ArithmeticException
{
double
phi = PI_OVER_2 - 2.0 * StrictMath.atan (coefficient_t),
difference = Double.MAX_VALUE;
int
iteration;
for (iteration = 0;
iteration < 15 &&
difference > 0.0000000001;
iteration++)
{
double
eccentricity_sine_phi = Eccentricity * StrictMath.sin (phi),
new_phi = PI_OVER_2 - 2.0
* StrictMath.atan (coefficient_t
* StrictMath.pow
(
(1.0 - eccentricity_sine_phi) /
(1.0 + eccentricity_sine_phi),
E_over_2
));
difference = Math.abs (new_phi - phi);
phi = new_phi;
}
if (iteration == 15)
throw new ArithmeticException (ID + '\n'
+ "Computation of coefficient phi2 failed to converge\n"
+ "using coefficient t of " + coefficient_t + '.');
return phi;
}
}
pirl-2.3.8/PIRL/Image_Tools/package.html 0000644 0001750 0001750 00000003705 11742733714 017613 0 ustar mathieu mathieu
The HTTP_ImageInputStream implements the ImageInputStream interface for a
remotely accessed file via the HTTP protocol. Random access is provided
by buffering source data using content ranging from the remote file.
Automatic URL redirect and reconnect is supported.
A set of classes are provided for accessing JP2 image file format
metadata boxes and its embedded JPEG2000 codestream segments
descriptions. The information is provided as a PVL Parameter Aggregate.
A set of Projection classes are provided for mapping coordinates between
image x,y and real world longitude,latitude values. The required map
projection information is contained in a PVL Parameter Aggregate used to
construct the Projection. A Projection factory method will examine the
parameters to determine the specific subclass that implements the
appropriate projection algorithms that is to be loaded and constructed.
pirl-2.3.8/PIRL/Configuration/ 0000755 0001750 0001750 00000000000 12052546520 015722 5 ustar mathieu mathieu pirl-2.3.8/PIRL/Configuration/Makefile 0000644 0001750 0001750 00000000653 10577661674 017410 0 ustar mathieu mathieu # Makefile for Java classes
#
# PIRL CVS ID: Makefile,v 1.5 2007/03/20 04:31:56 castalia Exp
# gmake syntax
# Location of the Java Classes for Mathematics.
JCM ?= /opt/java/jcm
JPATH ?= ../..:$(JCM)
JC ?= javac
.SUFFIXES: .java .class
.java.class:
${JC} -classpath ${JPATH} ${JFLAGS} $<
CLASSES = Configuration_Exception.class \
Configuration.class
all: classes
classes: ${CLASSES}
clean:
rm -f *.class
pirl-2.3.8/PIRL/Configuration/Configuration.java 0000644 0001750 0001750 00000310733 11742733240 021405 0 ustar mathieu mathieu /* Configuration
PIRL CVS ID: Configuration.java,v 1.55 2012/04/16 06:05:20 castalia Exp
Copyright (C) 2003-2007 Arizona Board of Regents on behalf of the
Planetary Image Research Laboratory, Lunar and Planetary Laboratory at
the University of Arizona.
This file is part of the PIRL Java Packages.
The PIRL Java Packages are free software; you can redistribute them
and/or modify them under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
The PIRL Java Packages are distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see
A Configuration is constructed by parsing source text in Parameter
Value Language (PVL) format (as read by a Parameter {@link
PIRL.PVL.Parser Parser}), or from another Configuration or PVL
Parameter. The {@link #Default_Source() Default_Source} will be
used if no source is specified. Except when a Configuration is
constructed as a copy of another Configuration (or Parameter
Aggregate), the {@link #Defaults Defaults} Parameters are always
included; if the special name {@link #DEFAULTS DEFAULTS} is
specified, only the Defaults Parameters will be in the
Configuration. In all cases, the Parameters in the Configuration
will be {@link #Coalesce() Coalesce}d together.
The parameters of a Configuration are refered to by their
pathname. The pathname may include a {@link
Parameter#Path_Delimiter() delimiter} (usually the '/' character)
separated sequence of names where each segment names a parameter
group within which subsequent named parameters are nested. A
pathname that begins with a delimiter is rooted at the top of the
Configuration parameter groupings (i.e. these pathnames have an
absolute location in the Configuration). Otherwise the pathname is
rooted at the first occurance of a parameter having the first
segment name (i.e. these pathnames have a relative location in the
Configuration).
There are a set of parameter names that are known to the
Configuration package:
In addition, the {@link #INCLUDE} parameter is recognized when
{@link #Include(boolean) Include} mode is enabled as a parameter
with a value that references another source of Parameters that is to
be included in the Configuration replacing the Include parameter.
Include files may be nested. Cyclical Include file (but not URL)
chains are caught.
@see PIRL.PVL.Parameter
@author Bradford Castalia - UA/PIRL
@version 1.55
*/
public class Configuration
extends Parameter
implements Cloneable
{
/** Class name and version identification.
*/
public static final String
ID = "PIRL.Configuration.Configuration (1.55 2012/04/16 06:05:20)";
/** The name of the configuration source from which the parameters have
been set.
This will be {@link #DEFAULTS DEFAULTS} if the Configuration was
constructed soley from the {@link #Defaults Defaults} Parameters. It
will be null if it was not constructed from the contents of a file
(i.e. it was constructed from a Parameter).
*/
private String
Config_Source = null;
/** The parameter name for the Java CLASSPATH: "Classpath".
*/
public static final String
CLASSPATH = "Classpath";
/** The parameter name for the application-specific hostname: "Host".
*/
public static final String
HOST = "Host";
/** The parameter name for the application-specific username: "User".
*/
public static final String
USER = "User";
/** The parameter name for a linked parameter used to create a new
Configuration: "Alias".
@see #Group(String)
*/
public static final String
ALIAS = "Alias";
/** The name of the Group containing the environment variable
parameters: "/Environment".
@see #Add_Environment()
*/
public static final String
ENVIRONMENT = Path_Delimiter () + "Environment";
/** The name of a parameter that refers to a file of parameters to be
included at that point in the Configuration: "@Include".
*/
public static final String
INCLUDE = "@Include";
/** The default automatic {@link #Include(boolean) Include} state.
*/
public static boolean
Include_Default = true;
private boolean
Include_Includes = Include_Default;
/** Parameter name prefix for the start of an {@link #Include(boolean)
Include} file when tracing is enabled.
*/
public static final String
INCLUDE_START = "INCLUDE_START";
/** Parameter name prefix for an {@link #CONTINUE_INCLUDE_ON_ERROR_FLAG
ignored error} report from an {@link #Include(boolean) Include} file
when tracing is enabled.
*/
public static final String
INCLUDE_ERROR = "INCLUDE_ERROR";
/** Parameter name prefix for the end of an {@link #Include(boolean)
Include} file when tracing is enabled.
*/
public static final String
INCLUDE_END = "INCLUDE_END";
/** The default automatic {@link #Include(boolean) Include} tracing flag.
*/
public static boolean
Include_Tracing_Default = false;
private boolean
Include_Tracing = Include_Tracing_Default;
/** {@link #INCLUDE} parameter value flag that, when
found at the beginning of the value, causes an error on the
include - the source does not exists - to be ignored and
the include skipped.
*/
public static final String
CONTINUE_INCLUDE_ON_ERROR_FLAG = "-";
/** The name of the internal default parameters: "DEFAULTS".
*/
public static final String
DEFAULTS = "DEFAULTS";
/** The name of the default configuration source: initially "DEFAULTS".
*/
public static String
Default_Source = DEFAULTS;
/** The default parameters conditionally set during {@link
#Configure(InputStream) configuration}.
The default parameters are:
When a duplicate Assignment parameter pathname is found while
{@link #Coalesce() coalescing} the Configuration, give preference
to the first parameter; i.e. remove all but the first of any
duplicate pathname parameters.
*/
public static final int
PREFER_FIRST_PARAMETER = 1;
/** The last duplicate parameter in the list gets preference when
coalescing.
When a duplicate Assignment Parameter pathname is found while
{@link #Coalesce() coalescing} the Configuration, give preference
to the last parameter; i.e. remove all but the last of any
duplicate pathname parameters.
*/
public static final int
PREFER_LAST_PARAMETER = -1;
/** Duplicate parameters in the list when coalescing causes an
exception.
When a duplicate Assignment Parameter pathname is found while
{@link #Coalesce() coalescing} the Configuration, a
Configuration_Exception will be thrown.
*/
public static final int
THROW_ON_DUPLICATE_PARAMETERS = 0;
/** The default {@link #Duplicate_Parameter_Action()}.
*/
public static int
Duplicate_Parameter_Action_Default
= THROW_ON_DUPLICATE_PARAMETERS;
private int
Duplicate_Parameter_Action
= Duplicate_Parameter_Action_Default;
/** The default {@link #Case_Sensitive()} state.
*/
public static boolean
Case_Sensitive_Default = false;
/** Is parameter name matching case sensitive?
*/
private boolean
Case_Sensitive = Case_Sensitive_Default;
public static final String
NL = System.getProperty ("line.separator");
// DEBUG control.
private static final int
DEBUG_OFF = 0,
DEBUG_GET = 1 << 0,
DEBUG_SET = 1 << 1,
DEBUG_CONFIGURE = 1 << 2,
DEBUG_INCLUDE = 1 << 3,
DEBUG_UTILITY = 1 << 4,
DEBUG_ALL = -1,
DEBUG = DEBUG_OFF;
/*==============================================================================
Constructors
*/
/** Constructs a default Configuration.
The {@link #Defaults} are used to set the initial parameters. {@link
#DEFAULTS} is the name of this Configuration.
*/
public Configuration ()
{
try {Configure (DEFAULTS);}
catch (Configuration_Exception exception)
{/* This shouldn't happen if the Defaults are OK. */}
}
/** Constructs a Configuration using the specified source.
@param source The source String reference for the Configuration
PVL. This may be in the form of a URL representation. If null,
the {@link #Default_Source() Default_Source} is used.
@throws IllegalArgumentException If the source is not a URL and
no file or system resource can be found with the source name.
@throws Configuration_Exception If the source can not be read or
successfully parsed for parameters, {@link #INCLUDE} files could
not be included, or there was a problem coalescing the
parameters (probably due to a duplicate parameter name).
@see #Configure(String)
@see #Include(boolean)
*/
public Configuration
(
String source
)
throws Configuration_Exception
{Configure (source);}
/** Constructs a Configuration using the specified URL.
@param url A URL object to use as the source of Configuration
PVL.
@throws Configuration_Exception If a stream can not be opened from
the URL, there was a problem while parsing the source for
parameters, {@link #INCLUDE} files could not be included, or
there was a problem coalescing the parameters (probably due to a
duplicate parameter name).
@see #Configure(URL)
@see #Include(boolean)
*/
public Configuration
(
URL url
)
throws Configuration_Exception
{Configure (url);}
/** Constructs a Configuration using the specified InputStream.
@param stream An InputStream object to use as the source of
Configuration PVL.
@throws Configuration_Exception If there was a problem while parsing
the stream for parameters, {@link #INCLUDE} files could not be
included, or there was a problem coalescing the parameters
(probably due to a duplicate parameter name).
@see #Configure(InputStream)
@see #Include(boolean)
*/
public Configuration
(
InputStream stream
)
throws Configuration_Exception
{Configure (stream);}
/** Constructs a Configuration from a Parameter.
If the Parameter is null or empty (has the {@link Parameter#UNKNOWN}
classification) an empty Configuration with the name {@link
Parser#CONTAINER_NAME} is constructed. If the Parameter is an
Assignment it becomes the only parameter in a Configuration with the
name {@link Parser#CONTAINER_NAME}. If the Parameter is an
Aggregate, its Parameter list is copied into the new Configuration
which is given the name of the Aggregate (the Configuration is a
copy of the Parameter).
If automatic include is enabled any {@link #INCLUDE} parameters are
processed. Finally, the results are {@link #Coalesce() Coalesce}d.
N.B.: Only the provided Parameter is included in the new
Configuration; Defaults are not included.
@param parameter The Parameter which will be copied into this
Configuration.
@throws Configuration_Exception If the Parameter contents could not
be added to the new Configuration, {@link #INCLUDE} files could
not be included, or there was a problem coalescing the results
(probably due to duplicate parameter names).
@see #Coalesce()
@see #Include(boolean)
*/
public Configuration
(
Parameter parameter
)
throws Configuration_Exception
{
if (parameter != null)
{
try
{
if (parameter.Is_Aggregate ())
{
Data (parameter);
Name (parameter.Name ());
}
else
{
Add (new Parameter (parameter));
Name (Parser.CONTAINER_NAME);
}
if (Include_Includes)
Include ();
Coalesce ();
}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "Failed to construct a new Configuration from the \""
+ parameter.Name () + "\" Parameter."
+ exception_message (exception),
exception
);
}
}
else
Ensure_Aggregate_Configuration ();
}
/** Copies a Configuration.
This is the same as constructing a Configuration from a Parameter,
followed by copying over the Configuration characteristics {@link
#Case_Sensitive(boolean) case sensitivity}, {@link
#Duplicate_Parameter_Action(int) duplicate parameter handling},
{@link #Include(boolean) Include processing}, {@link
#Include_Tracing(boolean) Include tracing}, {@link #Defaults(boolean)
Defaults parameters inclusion} and the {@link #Source() filename} if
non-null;
N.B.: The state of this Configuration is used during the
copy, not the state of the copied Configuration. For example, copied
{@link #INCLUDE} parameters are processed if automatic {@link
#Include(boolean) Include} is enabled for this Configuration; the
automatic Include state of the Configuration being copied is not
used.
@param configuration The Configuration to be copied.
@throws Configuration_Exception If the Parameter contents could not
be added to the new Configuration, or there was a problem
coalescing the results (probably due to duplicate parameter
names).
@see #Configuration(Parameter)
*/
public Configuration
(
Configuration configuration
)
throws Configuration_Exception
{
this ((Parameter)configuration);
Config_Source = configuration.Config_Source;
Include_Includes = configuration.Include_Includes;
Include_Tracing = configuration.Include_Tracing;
Include_Defaults = configuration.Include_Defaults;
Duplicate_Parameter_Action = configuration.Duplicate_Parameter_Action;
Case_Sensitive = configuration.Case_Sensitive;
}
/** Clones a Configurtion.
@return An Object of class Configuration that is a copy of this
Configuration. This will be null if there was a problem making
the copy.
@see #Configuration(Configuration)
@see Object#clone()
@see Cloneable
*/
public Object clone ()
{
try {return new Configuration (this);}
catch (Configuration_Exception exception) {return null;}
}
/*==============================================================================
Accessors
*/
/** Gets the value(s) for a parameter at a pathname.
If specific is true then the values will be obtained from the {@link
#Specific_Parameter(String) Specific_Parameter}, otherwise the
{@link #Effective_Parameter(String) Effective_Parameter} will be
used.
@param pathname A parameter pathname.
@param specific true if only a parameter at the specific
pathname is acceptable, otherwise default values from an
effective parameter will do.
@return A Vector of zero or more values. Each element of the
Vector is either the String representation of a single
value, or is itself a Vector of the same kind.
*/
public Vector Get
(
String pathname,
boolean specific
)
{return Get (Parameter (pathname, specific));}
/** Gets the value(s) for a parameter at the Nth pathname.
@param pathname A parameter pathname.
@param specific true if only a parameter at the specific
pathname is acceptable, otherwise default values from an
effective parameter will do.
@param skip The number of matching parameters to skip
before selecting a parameter.
@return A Vector of zero or more values. Each element of the
Vector is either the String representation of a single
value, or is itself a Vector of the same kind.
@see #Get(String, boolean)
@see #Parameter(String, boolean, int)
*/
public Vector Get
(
String pathname,
boolean specific,
int skip
)
{return Get (Parameter (pathname, specific, skip));}
/** Gets the value(s) for a parameter at a specific pathname.
This is the same as using the {@link #Get(String, boolean) Get}
method with the specific argument being true.
@param pathname A parameter pathname.
@return A Vector of zero or more values. Each element of the
Vector is either the String representation of a single
value, or is itself a Vector of the same kind.
*/
public Vector Get_Specific
(
String pathname
)
{return Get (pathname, true);}
/** Gets one String value from the specific pathname.
@param pathname A parameter pathname.
@return The first String value from the specific parameter, or null
if there is no parameter value.
@see #Get_Specific(String)
@see #Get_One(Vector)
*/
public String Get_Specific_One (String pathname)
{return Get_One (Get (pathname, true));}
/** Gets the value(s) for the effective parameter at a pathname.
This is the same as using the {@link #Get(String, boolean) Get}
method with the specific argument being false.
@param pathname A parameter pathname.
@return A Vector of zero or more values. Each element of the
Vector is either the String representation of a single
value, or is itself a Vector of the same kind.
*/
public Vector Get
(
String pathname
)
{return Get (pathname, false);}
/** Gets one String value for the effective parameter at a pathname.
@param pathname A parameter pathname.
@return The first String value from the effective parameter, or
null if there is no value.
@see #Get(String)
@see #Get_One(Vector)
*/
public String Get_One (String pathname)
{return Get_One (Get (pathname, false));}
/** Gets the value(s) for the effective parameter at a pathname
where the parameter may be linked to another parameter through
its value.
A linked parameter is an assignment of a single String value in
which the value is the pathname of some other effective parameter.
If the parameter has more than one value it is not linked. The
returned Vector contains the value(s) of the first non-linked
parameter found. An empty Vector will be returned if no parameter is
found.
@param pathname A parameter pathname.
@return A Vector of zero or more values. Each element of the
Vector is either the String representation of a single
value, or is itself a Vector of the same kind.
*/
public Vector Get_Linked
(
String pathname
)
{
if ((DEBUG & DEBUG_GET) != 0)
System.out.println (">>> Configuration.Get_Linked: \"" + pathname + "\"");
Vector
value = Get (pathname),
link;
while (value.size () == 1 &&
(link = Get (Get_One (value))).size () != 0)
{
if ((DEBUG & DEBUG_GET) != 0)
System.out.println (" Linked to: " + link);
value = link;
}
if ((DEBUG & DEBUG_GET) != 0)
System.out.println ("<<< Configuration.Get_Linked: " + value);
return value;
}
/** Gets one String value for the effective, and possibly linked,
parameter at a pathname.
@param pathname A parameter pathname.
@return The first String value from the effective parameter, or
null if there is no value.
@see #Get_Linked(String)
@see #Get_One(Vector)
*/
public String Get_Linked_One (String pathname)
{return Get_One (Get_Linked (pathname));}
/** Gets the value(s) for a Parameter.
@param parameter The Parameter from which to get value(s).
@return A Vector of zero or more values. Each element of the
Vector is either the String representation of a single
value, or is itself a Vector of the same kind.
@see #Get(Value)
*/
public Vector Get
(
Parameter parameter
)
{
Value
value = null;
if (parameter != null)
{
if ((DEBUG & DEBUG_GET) != 0)
System.out.println ("Configuration.Get: parameter \""
+ parameter.Path_Name () + "\"");
try {value = parameter.Value ();}
catch (PVL_Exception exception)
{/* The parameter is not an Assignment. */}
}
return Get (value);
}
/** Gets one String value from the Get Vector.
@param parameter The Parameter from which to get a value.
@return The first String value from the Vector, or null if there is
no value.
@see #Get(Parameter)
@see #Get_One(Vector)
*/
public String Get_One
(
Parameter parameter
)
{return Get_One (Get (parameter));}
/** Gets the value(s) for a Parameter Value.
@param value The Value from which to get value(s).
@return A Vector of zero or more values. Each element of the
Vector is either the String representation of a single
value, or is itself a Vector of the same kind.
*/
public static Vector Get
(
Value value
)
{
if ((DEBUG & DEBUG_GET) != 0)
System.out.println ("Configuration.Get value: " + value);
Vector
values = new Vector ();
if (value != null)
{
if (value.Is_Array ())
{
ListIterator
list = value.listIterator ();
while (list.hasNext ())
{
value = (Value)list.next ();
if (value.Is_Array ())
values.add (Configuration.Get (value));
else
{
try {values.add (value.String_Data ());}
catch (PVL_Exception exception)
{/* Shouldn't happen. */}
}
}
}
else
{
try {values.add (value.String_Data ());}
catch (PVL_Exception exception)
{/* Shouldn't happen. */}
}
}
return values;
}
/** Gets one String value from the Get Vector.
@param value The Value from which to get a value.
@return The first String value from the Vector, or null if there is
no value.
@see #Get(Value)
@see #Get_One(Vector)
*/
public String Get_One (Value value)
{return Get_One (Get (value));}
/** Gets the first String value from a Vector of values.
@param values The Vector to search.
@return The first String from the Vector, or null if none is found.
@see #Get_One(Vector, int)
*/
public static String Get_One
(
Vector values
)
{return Get_One (values, 0);}
/** Gets the indexed String value from a Vector of values.
The Vector is searched for the first non-Vector Object and its
{@link Object#toString() toString} value is returned. Vector Objects
are searched as they are encountered (i.e. depth-wise). Since the
Vector is presumed to be the values Vector returned from a Get
method, the first non-Vector Object should be the first String value
of a Configuration parameter (nevertheless, all Objects should have
a toString method).
@param values The Vector to search.
@param index The index of the element in the values.
@return The indexed String from the Vector, or null if none is found.
*/
public static String Get_One
(
Vector values,
int index
)
{
if (values != null &&
values.size () > 0 &&
values.size () > index)
{
Object
value = values.elementAt (index);
if (value instanceof Vector)
return Get_One ((Vector)value, 0);
return value.toString ();
}
return null;
}
/** Gets a numerical value.
The first available parameter value found at the pathname is
converted to a binary double value.
@param pathname A parameter pathname.
@param default_value The default value to use if the parameter can
not be found.
@return The numerical value of the parameter, or the default value
if the parameter can not be found or does not have a numerical
value.
*/
public double Get_Number
(
String pathname,
double default_value
)
{
String
value = Get_One (pathname);
if (value != null)
{
try {return Double.parseDouble (value);}
catch (NumberFormatException exception) {}
}
return default_value;
}
/** Tests if a parameter has a logically true value.
The first available parameter value found at the pathname is
examined for a logically true value. A paremeter is considered to
have a logically true value if it is any one of (case ignored):
"ENABLED", "TRUE", "YES", "ON", "Y", or "1".
@param pathname A parameter pathname.
@param default_flag The default value to use if the parameter can
not be found.
@return true if the parameter has an enabled value; false otherwise.
The default_flag value is returned if the parameter can not be found.
*/
public boolean Enabled
(
String pathname,
boolean default_flag
)
{
String
value = Get_One (pathname);
if (value == null)
return default_flag;
if (value.equalsIgnoreCase ("ENABLED") ||
value.equalsIgnoreCase ("TRUE") ||
value.equalsIgnoreCase ("YES") ||
value.equalsIgnoreCase ("ON") ||
value.equalsIgnoreCase ("Y") ||
value.equalsIgnoreCase ("1"))
return true;
return false;
}
/** Gets the Configuration parameters for a group.
All parameters for a named group, plus all default parameters for
the group, are collected into a new Configuration that will have the
name of the group. Default parameters are all Assignment parameters
in all parents of the group parameter. These parameters are {@link
Configuration#Set_Conditionally(String, Object) Set_Conditionally}
in the new configuration such that parameters closest to the group
(a parent is closer than a grandparent) have precedence when there
are parameters with the same name.
If an Assignment parameter with the group name is found instead of
an Aggregate parameter, its value is taken to be the name of the
Aggregate parameter name to use. Such a parameter is a "link" to the
actual group parameter, which gives the group parameter an "alias"
name. This allows configuration parameter groups to be known by
different names. Link parameters may refer to other link parameters.
If the extracted configuration is an alias it will be given an
{@link Configuration#ALIAS ALIAS} parameter having the value that is
the name of the alias group.
@param group The name of the configuration group to extract.
@return A Configuration with all of the group's parameters,
or null if the group could not be found.
@throws Configuration_Exception If the Parameter group could not be
assembled into a new Configuration.
*/
public Configuration Group
(
String group
)
throws Configuration_Exception
{
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println (">>> Configuration.Group: " + group);
Configuration
group_configuration = null;
Parameter
parameter = null;
String
alias = group;
while ((parameter = Find (alias, Case_Sensitive, parameter)) != null &&
! parameter.Is_Aggregate ())
{
if (parameter.Is_Assignment ())
{
try
{
// Follow name aliases (links).
if (parameter.Value () != null &&
! (alias = parameter.Value ().String_Data ()).equals ("") &&
! alias.equals (group))
{
// Find the new name from the top.
parameter = null;
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println (" alias: " + alias);
}
}
catch (PVL_Exception exception)
{/* Shouldn't happen */ return null;}
}
}
if (parameter != null)
{
group_configuration = new Configuration (parameter);
if (! alias.equals (group))
{
group_configuration.Set (Configuration.ALIAS, alias);
group_configuration.Name (group);
}
// Bring down all the Assignments from the parents.
Parameter
parent = parameter;
while ((parent = parent.Parent ()) != null)
{
ListIterator
list = parent.listIterator ();
while (list.hasNext ())
{
parameter = (Parameter)list.next ();
try
{
if (parameter.Is_Assignment ())
group_configuration.Set_Conditionally
(new Parameter (parameter));
}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "Unable to copy group parameter \""
+ parameter.Name () + "\"."
+ exception_message (exception),
exception
);
}
}
}
group_configuration.Coalesce ();
}
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println ("<<< Configuration.Group: "
+ (! (group_configuration == null)));
return group_configuration;
}
/*-----------------------------------------------------------------------------
*/
/** Sets a parameter at a specified pathname location to the value
of an Object.
The Object may be of any type acceptable for use in creating a
Parameter Value. This includes Vectors of Objects which will set
the parameter to the corresponding Value array. A null value will
result in an empty, Token, parameter.
When the value of an existing parameter is not to be replaced, the
availability of an {@link #Effective_Parameter(String)
Effective_Parameter} is sufficient to prevent the creation of a new
parameter. However, when replace is true, a parameter will be
created at the specific pathname if it does not already exist.
Note: If an existing parameter is found for the pathname,
whether specific or effective, that does not have a value, its
always assigned the new value.
Only parameters assigned a value - not parameter groups - may have
their value set. If the parameter does not exist a new parameter is
created and assigned the value.
@param pathname The pathname of the parameter whose value is to
be set.
@param value The value that will be assigned to the parameter.
@param replace If true, replace the values of existing parameters
with the new value; if false, do not replace existing values.
@return true if a previous value was replaced, or false if the
parameter is being set for the first time.
@throws Configuration_Exception If a new parameter could not be
created (possibly because the pathname is null), or the value
could not be set.
@see Parameter#Value(Object)
*/
public synchronized boolean Set
(
String pathname,
Object value,
boolean replace
)
throws Configuration_Exception
{
if (pathname == null)
throw new Configuration_Exception
(
ID + NL
+ "Unable to Set a parameter with a null pathname."
);
if ((DEBUG & DEBUG_SET) != 0)
System.out.println
(">>> Set: " + pathname + " to " + value
+ " (replace = " + replace + ")");
// Use effective parameters when not replacing (replace == specific).
Parameter
parameter = Parameter (pathname, replace);
if ((DEBUG & DEBUG_SET) != 0)
System.out.println
("Set: " + pathname
+ ((parameter == null) ? " not found." : " found."));
Value
old_value = null;
if (parameter == null)
{
// Create a new (initially empty) parameter.
parameter = group_parameter (pathname);
if ((DEBUG & DEBUG_SET) != 0)
System.out.println
("Set: new parameter - " + parameter.Path_Name ());
}
else
{
// Get the previous value.
try {old_value = parameter.Value ();}
catch (PVL_Exception exception) {/* Shouldn't happen. */}
}
if (replace || old_value == null)
{
// Replace the parameter's value.
if ((DEBUG & DEBUG_SET) != 0)
System.out.println
("Set: replacing " + old_value + " with " + value);
try {parameter.Value (value);}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "Unable to Set parameter \"" + pathname + "\""
+ " to value \"" + value + "\"."
+ exception_message (exception),
exception
);
}
}
if ((DEBUG & DEBUG_SET) != 0)
System.out.println
("<<< Set: Previous value - "
+ ((old_value == null) ? "false" : "true"));
return (old_value == null) ? false : true;
}
/** Sets the value of a parameter at a pathname.
A new parameter is created with the value if a parameter with the
pathname does not exist. Otherwise the existing value is replaced.
This is the same as using the {@link #Set(String, Object, boolean)
Set} method with a replace argument of true.
@param pathname The pathname of the parameter whose value is to
be set.
@param value The value that will be assigned to the parameter.
@return true if a previous value was replaced, or false if the
parameter is being set for the first time.
@see #Set(String, Object, boolean)
*/
public boolean Set
(
String pathname,
Object value
)
throws Configuration_Exception
{return Set (pathname, value, true);}
/** Sets the value of a new parameter at a pathname.
A new parameter is created with the value if a parameter with the
pathname does not exist. Otherwise the existing value is left
unchanged. This is the same as using the {@link #Set(String, Object,
boolean) Set} method with a replace argument of false.
@param pathname The name of the new parameter.
@param value The value that will be assigned to the parameter.
@return true if a previous value was replaced, or false if the
parameter is being set for the first time.
@throws Configuration_Exception If there was a problem setting any
parameter value.
@see #Set(String, Object, boolean)
*/
public boolean Set_Conditionally
(
String pathname,
Object value
)
throws Configuration_Exception
{return Set (pathname, value, false);}
/** Sets all of the entries of an array of String arrays as
Configuration parameters.
Each entry of the primary array is taken to be an array of Strings.
The first String is a parameter pathname and all remaining Strings
in the array are values for the parameter. A parameter pathname
without any following parameter value(s) will be skipped.
@param parameter_table The table of parameter names and
values.
@param replace If true, replace the values of existing parameters
with the new value; if false, do not replace existing values.
@throws Configuration_Exception If there was a problem setting any
parameter value.
@see #Set(String, Object, boolean)
*/
public void Set
(
String[][] parameter_table,
boolean replace
)
throws Configuration_Exception
{
Vector
values = new Vector ();
for (int element = 0;
element < parameter_table.length;
element++)
{
values.clear ();
int
value;
for (value = 1;
value < parameter_table[element].length;
value++)
values.add (parameter_table[element][value]);
if (value > 1)
{
try
{
if (values.size () == 1)
// Single value (don't create an Array Value).
Set
(
parameter_table[element][0],
(String)values.elementAt (0),
replace
);
else
Set
(
parameter_table[element][0],
values,
replace
);
}
catch (Configuration_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "During Set of \"" + parameter_table[element][0]
+ "\" Strings array entry " + element + "."
+ exception_message (exception),
exception
);
}
}
}
}
/** Sets all of the entries of an array of String arrays.
An existing parameter has its value replaced, otherwise a new
parameter is created
@param parameter_table The table of parameter names and
values.
@throws Configuration_Exception If there was a problem setting any
parameter value.
@see #Set(String[][], boolean)
@see #Set(String, Object)
*/
public void Set
(
String[][] parameter_table
)
throws Configuration_Exception
{Set (parameter_table, false);}
/** Conditionally sets all of the entries of an array of String arrays.
New parameters are created; existing parameters are unchanged.
@param parameter_table The table of parameter names and
values.
@throws Configuration_Exception If there was a problem setting any
parameter value.
@see #Set(String[][], boolean)
@see #Set_Conditionally(String, Object)
*/
public void Set_Conditionally
(
String[][] parameter_table
)
throws Configuration_Exception
{Set (parameter_table, false);}
/** Sets parameters in the Configuration to correspond with the
contents of another parameter.
For an Assignment parameter, a parameter in the Configuration at
the same pathname location is assigned the same parameter value.
For a parameter group, all of its members are recursivley set in
the Configuration.
The {@link Parameter#Path_Name() pathname} of each parameter that
is set is made to appear to be rooted at the Configuration root.
Thus the location of each parameter set in the Configuration will
be at the same relative location of the source parameter in its
own hierarchy according to its own pathname. Referencing a
source parameter nested somewhere down in a hierachy will then
produce a Configuration parameter that is nested down to the same
relative location. However, when the intention is to root
the Configuration parameters relative to the source parameter being
at the root itself, then the source parameter should be copied
before being provided to this method:
Note: Freestanding source parameters (that are not located
in a group hierarchy) set Configuration parameters located at the
root.
@param parameter The source Parameter for setting in the
Configuration.
@param replace If true, replace the values of existing parameters
with the new value; if false, do not replace existing values.
@throws Configuration_Exception If there was a problem setting
any parameter in the Configuration.
@see #Set(String, Object, boolean)
*/
public void Set
(
Parameter parameter,
boolean replace
)
throws Configuration_Exception
{
if (parameter == null)
return;
if ((DEBUG & DEBUG_SET) != 0)
System.out.println (">>> Set:" + NL
+ " parameter: " + parameter.Path_Name () + NL
+ " class: " + parameter.Classification_Name () + NL
+ " replace: " + replace);
String
pathname;
if (parameter.Is_Aggregate ())
{
ListIterator
list = parameter.listIterator ();
while (list.hasNext ())
{
Parameter
new_parameter = (Parameter)list.next ();
if ((DEBUG & DEBUG_SET) != 0)
System.out.println
(" Set Aggregate entry " + new_parameter.Path_Name ());
pathname = Path_Name_to_Pathname (new_parameter.Path_Name ());
if (new_parameter.Is_Aggregate () && new_parameter.Is_Empty ())
group_parameter (pathname)
.Classification (new_parameter.Classification ());
else
{
try {Set (new_parameter, replace);}
catch (Configuration_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "During Set of parameter group \""
+ parameter.Name () + '"' + NL
+ " at entry " + list.previousIndex () + "."
+ exception_message (exception),
exception
);
}
}
}
}
else
{
pathname = Path_Name_to_Pathname (parameter.Path_Name ());
if (pathname.length () == 0)
pathname = parameter.Path_Name ();
// Use specific pathname.
if (replace || Parameter (pathname, true) == null)
{
Value
value = null;
try {value = parameter.Value ();}
catch (PVL_Exception exception) {}
Set (pathname, value);
// Just let Set throw any exception.
}
}
if ((DEBUG & DEBUG_SET) != 0)
System.out.println ("<<< Set parameter " + parameter.Path_Name ());
}
/** Sets parameters in the Configuration to correspond with the
contents of another parameter.
An existing Configuration parameter has its value replaced,
otherwise a new parameter is created
@param parameter The source Parameter for setting in the
Configuration.
@throws Configuration_Exception If there was a problem setting any
parameter value.
@see #Set(Parameter, boolean)
*/
public void Set
(
Parameter parameter
)
throws Configuration_Exception
{Set (parameter, true);}
/** Conditionally sets parameters in the Configuration to correspond
with the contents of another parameter.
New parameters are created; existing parameters are unchanged.
@param parameter The source Parameter for setting in the
Configuration.
@throws Configuration_Exception If there was a problem setting any
parameter value.
@see #Set(Parameter, boolean)
@see #Set_Conditionally(String, Object)
*/
public void Set_Conditionally
(
Parameter parameter
)
throws Configuration_Exception
{Set (parameter, false);}
/** Sets all occurances of a parameter with the specified name to have
the specified value.
Only existing parameters have their value reset. If there are no
parameters with the specified name, no new parameter is created.
@param name The parameter name to find. This should be a simple
name, not a pathname. If a pathname is specified, then only
parameters at the pathname will be modified; an absolute
pathname can only apply to a single parameter, but a relative
pathname may apply to more than one.
@param value The Object to be assigned as the value of each
parameter found.
@return true if at least one parameter was found, false otherwise.
@throws Configuration_Exception If there was a problem replacing a
parameter's value.
*/
public synchronized boolean Set_All
(
String name,
Object value
)
throws Configuration_Exception
{
if ((DEBUG & DEBUG_SET) != 0)
System.out.println (">>> Set_All (\"" + name + "\", " + value + ")");
boolean
found = false;
Parameter
pattern = new Parameter (name);
Selector
selection = new Selection ()
.Name (true)
.Specific (Case_Sensitive);
Parameter
parameter = null;
while ((parameter = Find (pattern, selection, parameter)) != null)
{
if (parameter.Is_Aggregate ())
continue;
found = true;
try
{
// Replace the parameter's value.
if ((DEBUG & DEBUG_SET) != 0)
System.out.println
("Set_All: replacing "
+ parameter.Path_Name () + ":" + parameter.Value ());
parameter.Value (value);
}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "Unable to Set parameter \"" + parameter.Path_Name () + "\""
+ " to value \"" + value + "\"."
+ exception_message (exception),
exception
);
}
}
return found;
}
/** Returns the group Parameter at the pathname.
This Parameter is created (as an empty Parameter) if it doesn't
exist; which means that any and all of its parent Parameters must
exist or will be created, too. If the pathname is relative (i.e.
does not begin with a {@link Parameter#Path_Delimiter() path
delimiter}) and the first segment of the pathname does not exist,
then it will be created at the root of the Configuration.
Note The Parameter returned will not be a group parameter if,
and only if, a new parameter was created.
@param pathname The pathname to a group parameter.
@return The Parameter at the pathname location.
@throws Configuration_Exception If there is a problem creating any
segment of the pathname, including if the pathname is null.
*/
private synchronized Parameter group_parameter
(
String pathname
)
throws Configuration_Exception
{
if ((DEBUG & DEBUG_SET) != 0)
System.out.println
("... group_parameter: " + pathname);
if (pathname == null)
throw new Configuration_Exception
(
ID + NL
+ "Null pathname for group_parameter!"
);
// Find only group parameters with the specified name.
Selector
selection = new Selection ()
.Name (true)
.Specific (Case_Sensitive)
.And (true)
.Classification (true);
Parameter
pattern;
try {pattern = new Parameter (pathname).Add (new Parameter ());}
catch (PVL_Exception exception)
{
// This shouldn't happen.
throw new Configuration_Exception
(
ID + NL
+ "Unable to construct group parameter pattern parameter!"
+ exception_message (exception),
exception
);
}
Parameter
parameter = Find (pattern, selection);
if ((DEBUG & DEBUG_SET) != 0 && parameter != null)
System.out.println
(" group_parameter: Found " + pathname);
if (parameter == null)
{
// No such parameter. Create a new one.
parameter = new Parameter (Basename (pathname));
try
{
// Get the parent Parameter in which to put it.
if ((pathname = Parent_Pathname (pathname)) != null)
{
if ((DEBUG & DEBUG_SET) != 0)
System.out.println
(" group_parameter: Add "
+ parameter.Path_Name () + " to " + pathname);
group_parameter (pathname).Add (parameter);
}
else
{
// There is no parent (the pathname is at the root).
if ((DEBUG & DEBUG_SET) != 0)
System.out.println
(" group_parameter: Add "
+ parameter.Path_Name () + " at root.");
Add (parameter);
}
}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "Unable to add a new \"" + pathname + "\" parameter."
+ exception_message (exception),
exception
);
}
}
return parameter;
}
/*-----------------------------------------------------------------------------
*/
/** Removes the parameter(s) at a pathname.
@param pathname A parameter pathname.
@param specific If true, remove only the parameter at the
specific pathname, otherwise remove all effective parameters
for the pathname.
@return true if a previous value was removed, or false if there
is no parameter at the pathname.
*/
public synchronized boolean Remove
(
String pathname,
boolean specific
)
{
Parameter
parameter;
boolean
removed = false;
if (specific)
{
if ((parameter = Specific_Parameter (pathname)) != null)
{
parameter.Parent ().Remove (parameter);
return true;
}
}
else
{
while ((parameter = Effective_Parameter (pathname)) != null)
{
parameter.Parent ().Remove (parameter);
removed = true;
}
}
return removed;
}
/** Removes the all of the effective parameters for the pathname.
This is the same as using the {@link #Remove(String, boolean)
Remove} method with the specific argument being false.
@param pathname A parameter pathname.
@return true If a previous value was removed, or false if there
were no effective parameters for the pathname.
*/
public boolean Remove
(
String pathname
)
{return Remove (pathname, false);}
/** Removes the parameter at the specific pathname.
This is the same as using the {@link #Remove(String, boolean)
Remove} method with the specific argument being true.
@param pathname A parameter pathname.
@return true If a previous value was removed, or false if there
was no parameter at the pathname.
*/
public boolean Remove_Specific
(
String pathname
)
{return Remove (pathname, true);}
/** Removes a group of parameters at a pathname.
The group of parameters at the pathname is removed.
@param pathname A group pathname.
@return true If a group was removed, or false if there was no
group at the pathname.
*/
public boolean Remove_Group
(
String pathname
)
{
boolean
removed = false;
Parameter
parameter;
if ((parameter = Parameter_at (pathname)) != null &&
parameter.Is_Aggregate ())
{
parameter.Parent ().Remove (parameter);
removed = true;
}
return removed;
}
/*-----------------------------------------------------------------------------
*/
/** Gets the name of the source from which the Configuration parameters
have been set.
@return The source name String for the Configuration. This will be a
source file pathname or URL if the Configuration was constructed
from such a source. This will be {@link #DEFAULTS DEFAULTS} if
the Configuration is based soley on the internal default
parameters. It will be the {@link Parser#CONTAINER_NAME} if the
Configuration was constructed from an Assignment Parameter
(including an empty Parameter) rather than an Aggregate. If the
Configuration was constructed from an Aggregate Parameter it
will be the name of the Aggregate Parameter.
*/
public String Source ()
{return Config_Source;}
/** Gets the name of the file from which the Configuration parameters
have been set.
@deprecated Replaced by {@link #Source()}
*/
public String Filename ()
{return Source ();}
/** Resets the Configuration from the contents of the source.
@param source The name of the configuration source.
@return This Configuration.
@throws Configuration_Exception If the source can not be read or
successfully parsed for parameters, or there was a problem
coalescing the parameters (probably due to a duplicate
parameter name).
@see #Configure(String)
*/
public Configuration Source
(
String source
)
throws Configuration_Exception
{
Configure (source);
return this;
}
/** Resets the Configuration from the contents of the source file.
@param filename The name of the configuration file.
@deprecated Replaced by {@link #Source(String)}
*/
public Configuration Filename
(
String filename
)
throws Configuration_Exception
{return Source (filename);}
/** Sets the default source name.
@param source The name of the new default source. If null, the
{@link #DEFAULTS DEFAULTS} name will be used.
*/
public static void Default_Source
(
String source
)
{
if ((Default_Source = source) == null)
Default_Source = DEFAULTS;
}
/** Sets the default filename.
@param filename The new default filename. If null, the {@link
#DEFAULTS DEFAULTS} name will be used.
@deprecated Replaced by {@link #Default_Source(String)}
*/
public static void Default_Filename
(
String filename
)
{Default_Source (filename);}
/** Gets the default source name.
@return The default source name.
@see #Default_Source(String)
*/
public static String Default_Source ()
{return Default_Source;}
/** Gets the default source name.
@return The default source name.
@deprecated Replaced by {@link #Default_Source()}
*/
public static String Default_Filename ()
{return Default_Source ();}
/** Sets the class relative to which a configuration file may be sought.
@param related_class The Class related to the configuration file
to be loaded.
@see #Configure(String)
*/
public static void Relative_to_Class
(
Class related_class
)
{Relative_to_Class = related_class;}
/** Gets the class relative to which a configuration file may be sought.
@return The Class related to the configuration file to be loaded.
@see #Relative_to_Class(Class)
*/
public static Class Relative_to_Class ()
{return Relative_to_Class;}
/** Ensure that this Configuration is an Aggregate.
If this Configuration is an Aggregate, nothing is done.
If this Configuration is not an Aggregate, it is made into one. If
this Configuration has the UNKNOWN classification (it is empty) it's
Classification is simply changed to GROUP. Otherwise a copy of the
Parameter that is currently this Configuration is added to this
Configuration, thus making this Configuration an Aggregate while
retaining the current Parameter. Then the name of this Configuration
is set to {@link Parser#CONTAINER_NAME}.
*/
private void Ensure_Aggregate_Configuration ()
{
if (! Is_Aggregate ())
{
if (Is_Unknown ())
Classification (GROUP);
else
{
try {Add (new Parameter (this));}
catch (PVL_Exception exception) {/* This is a good Parameter */}
}
Name (Parser.CONTAINER_NAME);
}
}
/*-----------------------------------------------------------------------------
*/
/** Sets the case sensitive mode for finding parameter names.
It is initially disabled by default.
@param enable If true, case sensitive matching is used.
@return The previous case sensitive mode;
*/
public boolean Case_Sensitive
(
boolean enable
)
{
boolean
previous_state = Case_Sensitive;
Case_Sensitive = enable;
return previous_state;
}
/** Gets the case sensitive mode for finding parameter names.
@return The case sensitive mode: true if case sensitive matching is
enabled.
@see #Case_Sensitive(boolean)
*/
public boolean Case_Sensitive ()
{return Case_Sensitive;}
/** Enables or disables automatic inclusion of {@link #Defaults}
parameters.
N.B.: This method controls the automatic inclusion of {@link
#Defaults} parameters for subsequent Configure operations. The
{@link #Defaults_Default default automatic defaults} state is
applied to the construction of new Configuration objects.
@param enable true if Defaults parameters are to be automatically
included; false otherwise.
@return The previous automatic Defaults state.
*/
public boolean Defaults
(
boolean enable
)
{
boolean
state = Include_Defaults;
Include_Defaults = enable;
return state;
}
/*==============================================================================
Methods
*/
/** Provides a String description of a Configuration formatted as a
list of the parameters and their values.
The description is suitable for saving to a file for later input.
@return The String listing all of the Configuration parameters.
*/
public String Description ()
{
StringWriter
description = new StringWriter ();
String
name = Name ();
description.write (Parser.CROSSHATCH);
description.write (" " + name + NL);
if (Config_Source != null)
description.write (Parser.CROSSHATCH + " From: " + Config_Source + NL);
Lister
lister = new Lister (description).Strict (false);
// Prevent the top level from being written.
Name (Parser.CONTAINER_NAME);
try {lister.Write (this);}
catch (Exception exception)
{
Name (name); // Restore the original name.
return exception.getMessage ();
}
Name (name); // Restore the original name.
if (lister.Warning () != null)
{
String_Buffer
warning = new String_Buffer (lister.Warning ().getMessage ());
warning.escape_to_special ();
description.getBuffer ()
.append (NL + "Warning:" + NL)
.append (warning.toString ());
}
return description.toString ();
}
/*-----------------------------------------------------------------------------
*/
/** Loads a Configuration from a configuration file.
If the source String is null or empty, the {@link #Default_Source()
Default_Source} String is used. If this is null the {@link #DEFAULTS}
name is used.
If the source String equals the {@link #DEFAULTS} name the
Configuration is {@link #Configure(InputStream) loaded from a null
stream}.
If a URL can be constructred from the source String the Configuration
is {@link #Configure(URL) loaded from the URL}.
An attempt is made to open a file input stream use the source String
as the file's pathname. If this fails and the source String is a
simple filename - it has no directory components - the user's home
directory pathname is prepended and another attempt is made to open a
file input stream (unless the simple filename is for the same file in
the user's home directory). If a stream is opened it is used to
{@link #Configure(InputStream) load} the Configuration.
The source String is then treated as a {@link
ClassLoader#getSystemResource(String) system resource location} in
the JVM classpath. This includes finding configuration files located
in jar files. If this fails, a {@link #Relative_to_Class(Class)
relative-to Class} has been specified and the source String is a
simple filename then the class's package pathname, if it can be
determined, is prepended to the source name and another attempt is
made to locate the system resource. If a system resource location is
found the Configuration is {@link #Configure(URL) loaded from the
URL}.
When a input source is found the {@link #Source() Source} is set to
the name of the source. If the source is a local file the absolute
pathname will be used. If the source is a URL, including a system
resource location URL, the URL will be used.
@param source A URL specification, pathname of a disk file or jar
resource, or the special {@link #DEFAULTS DEFAULTS} name. If
null, the {@link #Default_Source() Default_Source} will be
used.
@throws Configuration_Exception If the source does not refer to a
source that can be found, read or successfully parsed for
parameters, or there was a problem coalescing the parameters
(probably due to a duplicate parameter name).
@throws IllegalArgumentException If no configuration source can be
found for the source name.
@see #Configure(URL)
@see #Configure(InputStream)
@see #Source()
*/
public synchronized void Configure
(
String source
)
throws Configuration_Exception
{
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println (">>> Configure (source: " + source + ")");
if (source == null ||
source.length () == 0)
source = Default_Source;
if (source == null ||
source.length () == 0)
source = DEFAULTS;
String
config_source = null;
FileInputStream
stream = null;
if (! source.equals (DEFAULTS))
{
// Try to construct a URL from the source String.
URL
url = null;
try
{
url = new URL (source);
Configure (url);
return;
}
catch (MalformedURLException exception)
{/* Nope. Fall back... */}
// Try to find a local file.
File
file = new File (source);
config_source = file.getAbsolutePath ();
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println ("Configure: Trying " + config_source);
try {stream = new FileInputStream (file);}
catch (FileNotFoundException exception)
{
/* Nope. Fall back... */
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println
("Configure: No configuration file " + config_source);
}
if (stream == null &&
file.getName ().equals (source))
{
/* Just a simple filename.
Try looking for it in the user's home directory.
*/
String
pathname =
System.getProperty ("user.home") + File.separator + source;
if (! pathname.equals (config_source))
{
config_source = pathname;
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println ("Configure: Trying " + pathname);
try {stream = new FileInputStream (pathname);}
catch (FileNotFoundException exception)
{
/* Nope. Fall back... */
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println
("Configure: No configuration file " + pathname);
}
}
}
if (stream == null)
{
/* Try for a URL from a System Resource at the source location.
This can find a file inside a jar file.
*/
url = ClassLoader.getSystemResource (source);
if (url == null &&
Relative_to_Class != null &&
file.getName ().equals (source))
{
// Try for a class relative location.
try {url = ClassLoader.getSystemResource
(Relative_to_Class.getPackage ().getName ()
.replace ('.', File.separatorChar)
+ File.separator + source);}
catch (NullPointerException except) {}
}
if (url == null)
{
/* If url is null, then we were unable even to use the source
string to get a System Resource. At this point, we are out of
reasonable options and must throw an exception.
*/
throw new IllegalArgumentException
(
ID + NL
+ "Configure can't find source file \"" + source + "\"."
);
}
Configure (url);
return;
}
}
if (config_source != null)
Config_Source = config_source;
Configure (stream);
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println ("<<< Configure (source: " + source + ")");
}
/** Loads a Configuration from a URL.
The URL is used to open an InputStream as a source of configuration
parameters. If the URL is null then a null stream will be used. If a
stream is successfully opened from the URL, then the Configuration's
{@link #Source() Source} will be set to the URL String. The
Configuration is {@link #Configure(InputStream) loaded from the
InputStream}.
@param url The URL source of configuration parameters. May be null.
@throws Configuration_Exception If an InputStream can not be opened
from the URL, the stream could not be successfully parsed for
parameters, or there was a problem coalescing the parameters
(probably due to a duplicate parameter name).
@see #Configure(InputStream)
*/
public void Configure
(
URL url
)
throws Configuration_Exception
{
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println (">>> Configure (URL: " + url + ")");
InputStream
stream = null;
if (url != null)
{
try {stream = url.openStream ();}
catch (IOException exception)
{
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println ("Unable to open a stream from the URL "
+ url + NL
+ exception.getMessage ());
throw new Configuration_Exception
(
ID + NL
+ "Configure can't open URL -" + NL
+ url
+ exception_message (exception),
exception
);
}
Config_Source = url.toString ();
}
Configure (stream);
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println ("<<< Configure (URL: " + url + ")");
}
/** Loads a Configuration from an InputStream.
The stream is parsed for configuration parameters and their values
(parameter = value).
This method will first {@link Parameter#Remove_All() Remove_All}
current parameters from the Configuration. The InputStream is used
to construct a Parser from which all available parameters are {@link
Parameter#Add(Parser) Add}ed into this Configuration. If automatic
{@link #Defaults(boolean) Defaults} are enabled the internal
parameter {@link #Defaults Defaults} are then {@link
#Set_Conditionally(Parameter) Set_Conditionally}. If automatic file
{@link #Include(boolean) Include}s is enabled any {@link #INCLUDE}
parameters are found and the parameters from the files they
reference are {@link #Include() Include}d. Finally all parameters
are {@link #Coalesce() Coalesce}d together.
If, however, the InputStream is null, then only the Defaults will be
used.
The Configuration's {@link #Source() Source} will be
set to the special {@link #DEFAULTS DEFAULTS} name.
If this Configuration's Source is not null, then the {@link
Parameter#Name() Name} will be set to the same String; otherwise it
will simply be set to "InputStream."
@param stream The InputStream source of configuration parameters.
@throws Configuration_Exception If the stream can not be read or
successfully parsed for parameters, or there was a problem
coalescing the parameters (probably due to a duplicate
parameter name).
@see Parser#Parser(InputStream)
*/
public synchronized void Configure
(
InputStream stream
)
throws Configuration_Exception
{
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println (">>> Configure (InputStream)");
// Clear all current parameters.
Remove_All ();
if (stream != null)
{
try
{
// Add all parameters parsed from the stream.
Add ((Parser)(new Parser (stream)
.Strict (false)
.Crosshatch_Comments (true)
.Filter_Input (false)));
}
catch (PVL_Exception exception)
{
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println
("Configure can't Add Parameters from InputStream Parser -" + NL
+ exception.Message ());
if (exception.Message ().equals (PVL_Exception.FILE_IO))
throw new Configuration_Exception
(
ID + NL
+ "Configure can't read Parameters from InputStream Parser."
+ exception_message (exception),
exception
);
else
throw new Configuration_Exception
(
ID + NL
+ "Configure couldn't get Parameters from InputStream Parser."
+ exception_message (exception),
exception
);
}
}
else
{
// DEFAULTS
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println ("Configure: Using " + DEFAULTS);
Config_Source = DEFAULTS;
}
if (Config_Source != null)
{
/* Set the Configuration name to the name of its source file.
Only the basename of Config_Source is used because the full
pathname is likely to contain delimiters that are the same as
the Parameter reference path delimiter character. This will
confuse operations that use parameter pathname references which
are assembled from parameter names.
*/
File
filename = new File (Config_Source);
Name (filename.getName ());
}
else
Name ("InputStream");
// Ensure that an empty or single parameter configuration is a group.
Ensure_Aggregate_Configuration ();
if (Include_Defaults)
// Make sure all of the default parameters have been set.
Set_Conditionally (Defaults);
if (Include_Includes)
// Include all @include files.
Include ();
// Coalesce all the parameters.
Coalesce ();
if ((DEBUG & DEBUG_CONFIGURE) != 0)
System.out.println ("<<< Configure (InputStream)");
}
/** Adds environment variables to the Configuration.
All environment variables that can be obtained from the runtime
environment are added to the {@link #ENVIRONMENT} group. If the
group doesn't exist, it is appended to the end of the Configuration.
Each environment variable is used to conditionally set a parameter
in the Environment group; i.e. any existing parameters with the same
name as an environment variable do not have their values changed.
The value of an environment variable is always a single String
regardless of embedded spaces or commas.
@return This Configuration.
@see Host#Environment()
*/
public Configuration Add_Environment ()
throws Configuration_Exception
{
Parameter
environment_group = null;
try {environment_group = group_parameter (ENVIRONMENT);}
catch (Configuration_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "Unable to add Environment group."
+ exception_message (exception),
exception
);
}
if (! environment_group.Is_Aggregate ())
environment_group.Classification (Parameter.GROUP);
Properties
environment_variables = Host.Environment ();
Enumeration
variables = environment_variables.propertyNames ();
while (variables.hasMoreElements ())
{
String
name = (String)variables.nextElement ();
try
{
Set_Conditionally (ENVIRONMENT + Path_Delimiter () + name,
environment_variables.getProperty (name));
}
catch (Configuration_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "Unable to add Environment variable:" + NL
+ name + " = " + environment_variables.getProperty (name)
+ exception_message (exception),
exception
);
}
}
return this;
}
/** Enables or disables automatic {@link #Include() Include}s.
N.B.: This method controls the automatic include state for
subsequent Configure operations. The {@link #Include_Default
Include_Default} state is applied to the construction of new
Configuration objects.
@param enable true if automatic file includes is enabled;
false otherwise.
@return The previous automatic include state.
*/
public boolean Include
(
boolean enable
)
{
boolean
state = Include_Includes;
Include_Includes = enable;
return state;
}
/** Enables or disables {@link #Include() Include} file tracing.
Include file tracing inserts a TOKEN parameter at the beginning
of the included parameters with a name of the form:
where source is the URL or canonical pathname of the file
that was included. At the end of the included parameters another
TOKEN is inserted that has the same form, but with "START" replaced
by "END". If the source can not be found and the {@link
#CONTINUE_INCLUDE_ON_ERROR_FLAG} is specified as the include file
prefix, then a parameter with a name of the same form, but with
"START" replaced by "ERROR", is inserted, and its value is the error
message.
Warning: When the resulting parameters are {@link #Coalesce()
Coalesce}d the included parameters may be moved to new locations
outside the INCLUDE_START to INCLUDE_END sequence. Thus include file
tracing can only be advisory.
N.B.: This method controls include file tracing for
subsequent Configure operations. The {@link #Include_Tracing_Default
Include_Tracing_Default} state is applied to the construction of
new Configuration objects.
@param enable true if include file tracing is enabled;
false otherwise.
@return The previous include file tracing state.
*/
public boolean Include_Tracing
(
boolean enable
)
{
boolean
state = Include_Tracing;
Include_Tracing = enable;
return state;
}
/** Includes parameters from include files.
Every parameter named {@link #INCLUDE} is replaced with the
parameters included from the file named by the parameter's value.
The value may contain nested parameter references that are {@link
Reference_Resolver#Resolve(String) Resolve}d against the parameters
currently in the Configuration; this includes all parameters that
have been included so far.
Relative pathnames for include files are taken to be relative to the
directory of the file that contains the include parameter, if this
can be determined. This will be the location of the Configuration
{@link #Source() file} itself for top level include parameters.
Include parameters may refer to a URL. If this is a "file" URL, then
its directory can be used for relative includes contained within it.
Other types of URLs may also be used, but they may not contain
include parameters with relative filename references. Relative
filename references that do not have a including file from which a
directory can be determined (URLs or a Configuration that was not
constructed from a file with an identified pathname) will be located
using the same process as that used to {@link #Configure(String)
Configure} from a source name.
Recursive includes - an include parameter that refers to a parent
include file - are not allowed (throw a Configuration_Exception).
Parameters that are Aggregates or the Value is an Array are
ignored.
An include reference that begins with the {@link
#CONTINUE_INCLUDE_ON_ERROR_FLAG} will not cause an exception to be
thrown if the reference can not be accessed. This is particularly
useful if the existence of the include file is uncertain and its
lack is acceptable.
@return This Configuration.
@throws Configuration_Exception If an include filename contains a
nested reference that can not be resolved; would result in a
recursive include; does not refer to a source that can be
found, read or successfully parsed for parameters; or there was
a problem coalescing its parameters (probably due to a
duplicate parameter name).
*/
public synchronized Configuration Include ()
throws Configuration_Exception
{
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println (">>> Configuration.Include");
String
config_filename = null,
filename,
resolved_filename = null,
included_pathname,
name;
/* Stack of included files and their parameters.
The pathnames will be canonical pathnames or URLs.
*/
Stack
included_pathnames = new Stack (),
included_parameters = new Stack ();
// Top level include file is the Configuration file itself (if known).
if ((filename = Source ()) != null &&
! filename.equals (DEFAULTS))
{
if ((config_filename = the_filename (filename)) == null)
config_filename = filename; // A URL.
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println
(" Top level (Configuration) include: " + config_filename);
included_pathnames.push (config_filename);
}
Reference_Resolver
resolver = new Reference_Resolver ().Parameters (this);
Configuration
include_parameters = null;
int
include_index;
Parameter
parent = null,
parameter = null;
while ((parameter = Find (INCLUDE, false, parameter)) != null)
{
// The Aggregate containing the include parameter.
parent = parameter.Parent ();
// The index of the include parameter in it's parent's list.
include_index = parent.getIndex (parameter);
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println
(" Include found: " + parameter.Path_Name ());
if (! included_parameters.empty () &&
parameter == included_parameters.peek ())
{
/* The include parameter is the last one found.
This completes the search of the included parameters.
*/
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println (" Previous include.");
// Remove the include parameter.
parent.Remove (include_index);
// Pop the included pathnames and parameters lists.
included_pathnames.pop ();
included_parameters.pop ();
if (config_filename != null &&
included_pathnames.empty ())
// Retain the Configuration pathname.
included_pathnames.add (config_filename);
/*
Restart the search with the first parameter of
the last included parameter's Aggregate list.
*/
parameter = (Parameter)parent.getChildAt (0);
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println
(" Restarting search after " + parameter.Path_Name ());
continue;
}
try
{
if (parameter.Is_Aggregate () ||
parameter.Value ().Is_Array ())
// Ignore Aggregates and Arrays.
continue;
}
catch (PVL_Exception exception) {/* Shouldn't happen */}
// Resolve any references in the include parameter value.
try {resolved_filename = resolver.Resolve
(filename = parameter.Value ().String_Data ());}
catch (Throwable exception)
{
String
message = ID + NL
+ "Include of \"" + filename + '"'
+ included_list (included_pathnames) + NL
+ "contains a reference that could not be resolved." + NL
+ exception.getMessage ();
if (exception instanceof ParseException)
message += NL
+ "At location " +
((ParseException)exception).getErrorOffset ();
throw new Configuration_Exception (message, exception);
}
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println
(" Included: " + filename + NL
+" resolved: " + resolved_filename);
// Check for a continue-on-error flag.
boolean
continue_on_error = false;
if (resolved_filename.startsWith (CONTINUE_INCLUDE_ON_ERROR_FLAG))
{
continue_on_error = true;
resolved_filename = resolved_filename.substring
(CONTINUE_INCLUDE_ON_ERROR_FLAG.length ());
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println
(" continue: " + resolved_filename);
}
/* Determine the include pathname.
This will produce a canonical pathname for an absolute pathname
to an existing file. Otherwise the name remains unchanged.
When the name produces a non-file URL, null is returned to flag
that no file checking can be done.
*/
included_pathname = the_filename (resolved_filename);
if (included_pathname == null)
{
// URL.
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println (" URL");
included_pathname = resolved_filename;
}
else
{
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println (" File");
File
file = new File (included_pathname);
if (! included_pathnames.empty () &&
! file.isAbsolute ())
{
name = the_filename
((String)included_pathnames.peek ());
if (name != null)
// Make the included filename relative to the includer file.
included_pathname =
new File (name).getParent () +
File.separator +
included_pathname;
}
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println (" Source: " + included_pathname);
}
if (Include_Tracing)
{
try
{
// Insert INCLUDE_START before the include parameter.
parent.Insert (new Parameter
(INCLUDE_START + ':' + included_pathname), include_index++);
// Insert INCLUDE_END after the include parameter.
parent.Insert (new Parameter
(INCLUDE_END + ':' + included_pathname), include_index + 1);
}
catch (PVL_Exception exception) {/* Shouldn't happen */}
}
// Load the parameters (turn off auto-include, of course, and Defaults).
boolean
auto_include = Include (false),
defaults = Defaults_Default;
Defaults_Default = false;
try {include_parameters = new Configuration (included_pathname);}
catch (Exception exception)
{
if (continue_on_error &&
exception instanceof IllegalArgumentException)
{
// Remove the INCLUDE parameter.
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println
(" errored -" + NL
+ exception);
parent.Remove (include_index);
if (Include_Tracing)
{
// Insert an INCLUDE_ERROR parameter.
try {parent.Insert (new Parameter
(INCLUDE_ERROR + ':' + included_pathname)
.Value (exception.getMessage ()), include_index);}
catch (PVL_Exception except) {/* Shouldn't happen */}
}
// Restart the search with the parent's first parameter.
parameter = (Parameter)parent.getChildAt (0);
continue;
}
throw new Configuration_Exception
(
ID + NL
+ "Include of \"" + included_pathname + '"'
+ (resolved_filename.equals (filename) ?
"" : (NL + "resolved from \"" + filename + '"'))
+ included_list (included_pathnames) + NL
+ "is unable to obtain the parameters."
+ exception_message (exception),
exception
);
}
finally
{
Include (auto_include);
Defaults_Default = defaults;
}
// Check for recursive file include.
if ((included_pathname = the_filename (include_parameters.Source ()))
== null)
included_pathname = include_parameters.Source (); // URL.
if (included_pathnames.contains (included_pathname))
throw new Configuration_Exception
(
ID + NL
+ "Include of \"" + included_pathname + '"'
+ (resolved_filename.equals (filename) ?
"" : (NL + "resolved from \"" + filename + '"'))
+ included_list (included_pathnames) + NL
+ "would be recursive."
);
if (include_parameters.getChildCount () == 0)
{
// Empty include parameters list.
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println (" Include list is empty.");
parent.Remove (include_index);
parameter = null;
continue;
}
// Insert the new parameters before the include parameter.
try {parent.Insert
(include_parameters.List (), include_index);}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "Include of \"" + included_pathname + '"'
+ (resolved_filename.equals (filename) ?
"" : (NL + "resolved from \"" + filename + '"'))
+ included_list (included_pathnames) + NL
+ "was unable to insert the new parameters!"
+ exception_message (exception),
exception
);
}
/*
Note that the include parameter is left in place to mark the end
of the included parameters during the search for more include
parameters in the included parameters.
*/
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println
(" Included parameters:" + NL
+ include_parameters.Description ());
// Add the included pathname to the list.
included_pathnames.push (included_pathname);
included_parameters.push (parameter);
// Restart the search with the first Parameter in the current Aggregate.
parameter = (Parameter)parent.getChildAt (0);
}
if ((DEBUG & DEBUG_INCLUDE) != 0)
System.out.println ("<<< Configuration.Include");
return this;
}
/** Generates a listing of included files.
The listing is LIFO: the last file included is listed first
followed, on succeeding lines, by the file that included the
previous file. Each filename is enclosed in quotes and preceded by a
newline and "included from ". If the list of included files is
empty, the empty String is returned.
N.B.: The listing does not end with a new-line character.
@param included_pathnames The Vector of included filenames.
@return The included filenames listing String.
*/
private static String included_list
(
Stack included_pathnames
)
{
if (included_pathnames.isEmpty ())
return "";
String
included = "";
ListIterator
names = included_pathnames.listIterator (included_pathnames.size ());
while (names.hasPrevious ())
included += NL
+ "included from \"" + (String)(names.previous ()) + '"';
return included;
}
/** Gets a filename from what may be a URL.
An attempt is made to construct a URL from the argument. If this
succeeds the protocol is checked to see if it is a "file". If so
the canononical path from the URL is returned, otherwise null is
returned. If the URL can not be constructed or the canonical path
to an existing file can not be determined from a file URL the
original argument is returned.
@param string The initial filename.
@return A String, or null if the string is a non-file URL.
*/
private static String the_filename
(
String string
)
{
try
{
URL
url = new URL (string);
if (url.getProtocol ().equals ("file"))
{
File
file = new File (string = url.getPath ());
if (file.exists ())
string = file.getCanonicalPath ();
// else it's not an existing file.
}
else
// It's a non-file URL.
string = null;
}
catch (MalformedURLException exception)
{
// Not a URL.
File
file = new File (string);
if (file.isAbsolute () &&
file.exists ())
{
try {string = file.getCanonicalPath ();}
catch (IOException except) {}
}
}
catch (IOException exception) {/* Can't get the cononical path */}
return string;
}
/*==============================================================================
Utility functions
*/
/** Gets the pathname for a parameter at the previous group level.
The {@link #Basename(String) Basename} is removed from the pathname.
Then the pathname is shortened by one additional segment and the
basename appended back again. This has the effect of producing a
pathname with the same basename but at the same level as the parent
(thus it is the "uncle" to the original pathname :-). This is used
when percolating up a Parameter hierarchy looking for an effective
(default) parameter of a given name.
@param pathname The pathname to modify.
@return The pathname with the parent segment removed, or null
if the pathname has no parent segment.
*/
public static String Pathname_Uncle
(
String pathname
)
{
if (pathname == null)
return null;
int
end = pathname.lastIndexOf (Path_Delimiter ());
if (end <= 0)
return null;
int
start = pathname.lastIndexOf (Path_Delimiter (), end - 1);
if (start < 0)
return pathname.substring (++end);
if (start == 0)
return pathname.substring (end);
return pathname.substring (0, start) + pathname.substring (end);
}
/** Gets the Configuration pathname for a Parameter Path_Name.
A Parameter {@link Parameter#Path_Name() Path_Name} includes the
name of the root Aggregate parameter. A Configuration pathname does
not include the root name segment.
@param pathname A Parameter Path_Name.
@return The pathname stripped of the root segment, or the empty
String if the pathname only has a root segment.
*/
public static String Path_Name_to_Pathname
(
String pathname
)
{
if (pathname == null)
return null;
int
end = pathname.indexOf (Path_Delimiter (), 1);
if (end > 0)
return pathname.substring (end);
return "";
}
/** Gets the Configuration pathaname for a parameter.
@param parameter A parameter.
@return The pathname String for the parameter.
@see #Path_Name_to_Pathname(String)
*/
public static String Pathname
(
Parameter parameter
)
{return Path_Name_to_Pathname (parameter.Path_Name ());}
/** Gets the effective pathname for a specified pathname.
The effective pathname is the pathname of the {@link
#Effective_Parameter(String) Effective_Parameter} for the pathname.
@param pathname A parameter pathname.
@return The effective pathname for the pathname, or null if there
is none.
*/
public String Effective_Pathname
(
String pathname
)
{
Parameter
parameter = Effective_Parameter (pathname);
if (parameter != null)
return parameter.Path_from (this);
return null;
}
/** Gets the pathname to a parameter group.
Links will be followed: When an Assignment Parameter with the name
of the group is found its value will be taken as the new group name
to be sought until an Aggregate Parameter is found. A link chain is
not allowed to loop back to the original group name.
@param group The name of an Aggregate Parameter to be found.
@return The fully qualified pathname to the parameter group,
or null if the group can not be found.
*/
public String Group_Pathname
(
String group
)
{
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println (">>> Configuration.Group_Pathname: " + group);
if (group == null)
{
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println ("<<< Configuration.Group_Pathname: " + group);
return null;
}
Parameter
parameter = null,
pattern = new Parameter (group);
Selector
selection = new Selection ()
.Name (true)
.Specific (Case_Sensitive);
String
link = group;
while ((parameter = Find (pattern, selection, parameter)) != null &&
! parameter.Is_Aggregate ())
{
if (parameter.Is_Assignment ())
{
try
{
// Follow links.
if (parameter.Value () != null &&
! (link = parameter.Value ().String_Data ()).equals ("") &&
! (Case_Sensitive ?
link.equals (group) : link.equalsIgnoreCase (group)))
{
// Find the new name from the top.
pattern.Name (link);
parameter = null;
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println (" link: " + link);
}
}
catch (PVL_Exception exception) {/* Shouldn't happen */ return null;}
}
}
if (parameter != null)
link = Path_Name_to_Pathname (parameter.Path_Name ());
else
link = null;
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println ("<<< Configuration.Group_Pathname: " + link);
return link;
}
/** Gets the parameter for a pathname.
When specific is false and there is no parameter in the
Configuration at the specified pathname location, then a parameter
with the same {@link #Basename(String) Basename} is sought at
progressively higher levels of the path. The first parameter found
is returned, or null if no parameter is found.
Note: Only an Assignment (or Token) parameter will be found.
Aggregate parameters do not qualify because they have no value. A
Token has no value but can be assigned one.
@param pathname A parameter pathname.
@param specific true if only a parameter at the specific
pathname is acceptable, otherwise an effective parameter will
do.
@return The Parameter for the pathname, or null if there is none.
@see #Pathname_Uncle(String)
*/
public Parameter Parameter
(
String pathname,
boolean specific
)
{return Parameter (pathname, specific, 0);}
/** Gets the Nth parameter for a pathname.
The parameter is selected after skip parameters have been found
that match the pathname. If skip is 0, the first matching parameter
is selected; if skip is N, N matching parameters must be found
before the next matching parameter will be selected.
@param pathname A parameter pathname.
@param specific true if only a parameter at the specific
pathname is acceptable, otherwise an effective parameter will
do.
@param skip The number of matching parameters to skip.
@return The Parameter for the pathname, or null if there is none
found.
@see #Parameter(String, boolean)
*/
public Parameter Parameter
(
String pathname,
boolean specific,
int skip
)
{
if (pathname == null)
return null;
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println (">>> Configuration.Parameter (\"" +
pathname + "\", " + specific + ")");
// Find only non-Aggregate parameters with the specified name.
Parameter
pattern = new Parameter (pathname);
Selector
selection = new Selection ()
.Name (true)
.Specific (Case_Sensitive);
Parameter
parameter = null;
do
{
while ((parameter = Find (pattern, selection, parameter)) == null &&
! specific)
{
if ((pathname = Pathname_Uncle (pathname)) == null)
break;
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println (" Trying Pathname_Uncle: " + pathname);
pattern.Name (pathname);
}
}
// Accept only the Nth non-Aggregate parameter.
while (parameter != null &&
(parameter.Is_Aggregate () || skip-- > 0));
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println ("<<< Configuration.Parameter: " +
(parameter == null ? "not found." : "found"));
return parameter;
}
/** Gets the parameter or parameter group at a pathname.
Only the parameter at the specific pathname will be found. This is
similar to the {@link #Parameter(String, boolean) Parameter} method
used with specific=true. But unlike that method, this method may
return an Aggregate if that is what is found.
@param pathname A parameter pathname.
@return The Parameter for the pathname, or null if there is none.
*/
public Parameter Parameter_at
(
String pathname
)
{
if (pathname == null)
return null;
Parameter
pattern = new Parameter (pathname);
Selector
selection = new Selection ()
.Name (true)
.Specific (Case_Sensitive);
return Find (pattern, selection);
}
/** Gets the specific Parameter for a pathname.
This is the same as using the {@link #Parameter(String,
boolean) Parameter} method with the specfic
argument being true.
@param pathname A parameter pathname.
@return The Parameter for the pathname, or null if there is none.
*/
public Parameter Specific_Parameter
(
String pathname
)
{return Parameter (pathname, true);}
/** Gets the effective Parameter for a pathname.
This is the same as using the {@link #Parameter(String, boolean)
Parameter} method with the specific argument being false.
@param pathname A parameter pathname.
@return The effective Parameter for the pathname, or null if there
is none.
*/
public Parameter Effective_Parameter
(
String pathname
)
{return Parameter (pathname, false);}
/** Sets the duplicate parameter action during coalescing.
One of these actions may be specified:
The default action is to THROW_ON_DUPLICATE_PARAMETERS.
@param action The duplicate parameter action.
@return This Configuration
@see #Coalesce()
*/
public Configuration Duplicate_Parameter_Action
(
int action
)
{
if (action == 0)
Duplicate_Parameter_Action = THROW_ON_DUPLICATE_PARAMETERS;
else if (action > 0)
Duplicate_Parameter_Action = PREFER_FIRST_PARAMETER;
else if (action < 0)
Duplicate_Parameter_Action = PREFER_LAST_PARAMETER;
return this;
}
/** Gets the duplicate parameter action during coalescing.
@return The default parameter action.
@see #Duplicate_Parameter_Action(int)
*/
public int Duplicate_Parameter_Action ()
{return Duplicate_Parameter_Action;}
/** Coalesce all Aggregate parameters of the same name together.
Each Aggregate in the current list is compared, by name, against
all other Aggregates in the list. When a duplicate name is found
the parameters it contains are added to the end of the first
parameter in the list having the same name. Finally each Aggregate
is recursively coalesced in the same manner.
In addition, all Assignment (i.e. non-Aggregate) parameters in each
Aggregate are checked for duplicates and moved to the front of the
list of parameters.
The action taken when duplicate Assignment Parameter is encountered
depends on the current {@link #Duplicate_Parameter_Action(int)
Duplicate_Parameter_Action}. Byt default the actions is to throw
a Configuration_Exception.
@throws Configuration_Exception If there was a duplicate Assignment
parameter and the Duplicate_Parameter_Action is
THROW_ON_DUPLICATE_PARAMETERS, or there was a problem moving
parameters around in the list.
*/
public void Coalesce ()
throws Configuration_Exception
{
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println (">>> Coalesce");
coalesce (this);
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println ("<<< Coalesce");
}
private synchronized void coalesce
(
Parameter parameters
)
throws Configuration_Exception
{
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println (">>> coalesce: " + parameters.Path_Name ());
Vector
list;
try {
list = parameters.List ();
if (list == null)
{
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println ("<<< coalesce: " + parameters.Path_Name ());
return;
}
}
catch (PVL_Exception exception)
{
/* No list */
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println ("<<< coalesce: " + parameters.Path_Name ());
return;
}
int
this_index,
that_index,
total_parameters = list.size ();
if (total_parameters == 0)
{
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println ("<<< coalesce: " + parameters.Path_Name ());
return;
}
Parameter
this_parameter,
that_parameter,
/* Accumulation of Assignment Parameters in the current Parameter list.
It starts as an Assignment as a convenient flag that it is empty.
*/
assignments = new Parameter ();
for (this_index = 0;
this_index < total_parameters;
this_index++)
{
this_parameter = (Parameter)list.elementAt (this_index);
if (this_parameter.Is_Aggregate ())
{
for (that_index = this_index + 1;
that_index < total_parameters;
that_index++)
{
// Check the remainder of the list for matching Aggregates.
that_parameter = (Parameter)list.elementAt (that_index);
if (that_parameter.Is_Aggregate () &&
(Case_Sensitive ?
that_parameter.Name ()
.equals (this_parameter.Name ()) :
that_parameter.Name ()
.equalsIgnoreCase (this_parameter.Name ())))
{
try
{
this_parameter.Add
(parameters.Remove (that_index--).List ());
total_parameters--;
}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "During Coalesce of \"" + parameters.Name () + '"' + NL
+ " unable to Add to \""
+ this_parameter.Name ()
+ "\" the parameter List from \""
+ that_parameter.Name () + "\"."
+ exception_message (exception),
exception
);
}
}
}
// Coalesce the coalesced Aggregate.
coalesce (this_parameter);
}
else
{
// Check for a duplicate Assignment parameter.
if (assignments.Is_Aggregate () &&
(that_parameter = assignments.Find
(this_parameter.Name (), Case_Sensitive))
!= null)
{
switch (Duplicate_Parameter_Action)
{
case PREFER_FIRST_PARAMETER:
// Drop the duplicate from the parameters list.
parameters.Remove (this_index--);
total_parameters--;
// Move on to the next parameter in the list.
continue;
case THROW_ON_DUPLICATE_PARAMETERS:
String
this_value = null,
that_value = null;
try
{
this_value = this_parameter.Value ().toString ();
that_value = that_parameter.Value ().toString ();
}
catch (PVL_Exception exception) {/* Shouldn't happen. */}
throw new Configuration_Exception
(
ID + NL
+ "During Coalesce of \"" + parameters.Name () + '"' + NL
+ " duplicate parameter name - \""
+ this_parameter.Path_Name () + "\";" + NL
+ " original value - " + that_value + NL
+ " duplicate value - " + this_value
);
case PREFER_LAST_PARAMETER:
// Drop the assignments list duplicate.
assignments.Remove (that_parameter);
// Accumulate the parameters list duplicate.
}
}
try
{
// Move the the Assignment Parameter into the accumulated list.
assignments.Add
(parameters.Remove (this_index--));
total_parameters--;
}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "During Coalesce of \"" + parameters.Name () + '"' + NL
+ " while accumulating Assignment parameter \""
+ this_parameter.Name () + "\"." + NL
+ exception_message (exception),
exception
);
}
}
}
if (assignments.Is_Aggregate ())
{
// Insert the accumulated Assignments before the first Aggregate.
try {parameters.Insert (assignments.List (), 0);}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(
ID + NL
+ "During Coalesce of \"" + parameters.Name () + '"' + NL
+ " unable to move Assignment parameters to the front."
+ exception_message (exception),
exception
);
}
}
if ((DEBUG & DEBUG_UTILITY) != 0)
System.out.println ("<<< coalesce: " + parameters.Path_Name ());
}
/*==============================================================================
Helpers
*/
/** Get an exception message.
@param exception The Exception from which to obtain a message.
@return A String that begins with a NL sequence followed by the
message from the exception if the exception is not null and its
message is neither null nor empty.
*/
static private String exception_message
(
Throwable exception
)
{
String
message = NL;
if (exception != null)
{
String
exception_message = exception.getMessage ();
if (exception_message != null &&
exception_message.length () != 0)
message += exception_message;
}
return message;
}
/*==============================================================================
Application
*/
/** Assemble and report on the contents of a configuration.
The command line syntax is described by the {@link #Usage()
Usage} method.
Exit status:
0 - Success
Only the source of the configuration parameters is required. This
may be a filename or a URL.
The entire configuration, with all included configurations, will be
listed unless a specific parameter pathname is specified with the
-query or -find option. The only difference between -query and -find
is that the former never lists parameter comments. A parameter
pathname may be absolute or relative. All parameters having the
pathname will be listed. Pathname matching is not case sensitive
unless the -case_sensitive option is specified. If -pattern is
specified the pathname is taken to be a regular expression
{@link java.util.regex.Pattern Pattern}. The -query/-find option may be
used more than once to find more than one parameter.
N.B.This method always results in a System.exit with a
status of 1.
*/
public static void Usage ()
{
System.out.print
(ID + NL
+"Usage: Configuration The Configuration parameters may be assembled from any source of
Parameter Value Language (PVL) statements - a file, URL, or system
resource such as a jar file - or an existing Parameter object. Any
"@Include" parameter found is recursively processed as a source of PVL
statements to replace the "@Include" parameter. A set of basic default
parameters is always provided, and all environment variables are added
to the Configuration. A new Configuration has its parameters coalesced
so that groups of parameters of the same name result in a single group,
and duplicate parameters are removed (or throw an exception) on either
a first or last preference basis.
Methods are provided to get parameter values by name. The name may
be a simple name or an absolute or relative pathname. The name may be
treated as case sensitive or not. When a parameter value is the name of
another parameter the first parameter may be treated as a link to the
value of the second parameter. When a named parameter can not be found,
a search up the Parameter hierarchy may be automatically done for a
parameter of the specified name; this allows default values to be
provided at a higher level for all parameter groups at a lower level.
All parameter values are returned as Strings. The value of a parameter
may be a single value or an Array of values; if desired, only the first
value of an Array will be obtained. An entire Group of parameters may
be obtained as a sub-Configuration, with all parameters from higher
levels than the group automatically incorporated into the new
Configuration.
Methods are provided to set parameter values by name using the
String representation of any Object. The setting of the new value may
be conditional on a parameter of the specified name not already being
present in the Configuration, and all occurances of a parameter name
may be set. These methods indicate when the value of an existing
parameter was changed as opposed to creating a new parameter. Parameter
values may also be set using the name and value of another Parameter or
from an array of name, value String pairs.
Methods are provided to remove parameters by name. Either a specific
parameter or all parameters with a matching name may be removed.
Because a Configuration is a subclass of Parameter, it may be
manipulated using any of the Parameter methods.
@see PIRL.PVL
pirl-2.3.8/PIRL/Configuration/Configuration 0000755 0001750 0001750 00000004055 11652356205 020467 0 ustar mathieu mathieu #!/usr/bin/perl
#
# A wrapper for the Java Configuration application.
#
# The PIRL_JAVA_HOME enviroment variable, if it is set, will be
# prepended to the java runtime classpath. The value of PIRL_JAVA_HOME
# may be a directory pathname where the PIRL subdirectory and all its
# class files is located; or it may be the pathname to a jar file -
# e.g. PIRL.jar - containing the class files for the PIRL Java
# Packages.
#
# N.B.: If the PIRL_JAVA_HOME enviroment variable is not set but the
# /opt/java/PIRL pathname exists, then /opt/java will be used for the
# value of PIRL_JAVA_HOME.
#
# If the CLASSPATH environment variable is set its value is appended to
# the java runtime classpath.
#
# The location of the following third party packages are expected to be
# in the java runtime classpath or provided as the value of an environment
# variable having the names listed here:
#
# JCM - http://math.hws.edu/javamath
#
# The pathname to the Java Components for Mathematics jar file or the
# root directory where its class files are located. This package is a
# required dependency.
# Default: $PIRL_JAVA_HOME/jcm/jcm_data.jar
#
#
# Note: On Apple OS X (Darwin) systems the Java Virtual Machine will
# automatically include jar files in the ~/Library/Java/Extensions and
# /Library/Java/Extensions directories, if they exist, in the java
# runtime classpath.
#
#
# CVS ID: Configuration,v 1.3 2011/10/27 22:34:45 castalia Exp
$CLASSPATH = $ENV{"CLASSPATH"};
$PIRL_JAVA_HOME = $ENV{"PIRL_JAVA_HOME"};
$PIRL_JAVA_HOME = "/opt/java"
if (! $PIRL_JAVA_HOME &&
-e "/opt/java/PIRL");
Add_to_CLASSPATH ($PIRL_JAVA_HOME);
$JCM = "$PIRL_JAVA_HOME/jcm/jcm_data.jar"
unless $JCM = $ENV{"JCM"};
Add_to_CLASSPATH ($JCM);
@Arguments = (java);
push @Arguments, "-cp", $CLASSPATH
if $CLASSPATH;
push @Arguments, "PIRL.Configuration.Configuration", @ARGV;
exec @Arguments;
sub Add_to_CLASSPATH
{
my ($pathname) = @_;
if (-e "$pathname")
{
if ($CLASSPATH)
{
$CLASSPATH = "$CLASSPATH:$pathname"
unless "$pathname" =~ /"$pathname"/;
}
else
{
$CLASSPATH = $pathname;
}
}
}
pirl-2.3.8/PIRL/Configuration/Configuration_Exception.java 0000644 0001750 0001750 00000006274 11742733240 023425 0 ustar mathieu mathieu /* Configuration_Exception
PIRL CVS ID: Configuration_Exception.java,v 1.7 2012/04/16 06:05:20 castalia Exp
Copyright (C) 2003-2012 Arizona Board of Regents on behalf of the
Planetary Image Research Laboratory, Lunar and Planetary Laboratory at
the University of Arizona.
This file is part of the PIRL Java Packages.
The PIRL Java Packages are free software; you can redistribute them
and/or modify them under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
The PIRL Java Packages are distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see
@author Bradford Castalia, Christian Schaller - UA/PIRL
@version 1.7
*/
public class Configuration_Exception
extends java.lang.Exception
{
/** Class identification name with source code version and date.
*/
public static final String
ID = "PIRL.Configuration.Configuration_Exception (1.7 2012/04/16 06:05:20)";
/*==============================================================================
Constructors
*/
/** Constructs a Configuration_Exception with a message and a cause.
N.B.: Once a cause is set it can not be changed. Therefore,
though it is allowed to set the cause to null, the
Configuration_Exception will not do this to avoid the situation of
not being able to replace a null cause with a valid cause. Use the
{@link Throwable#initCause(Throwable)} method to provide a cause
after the Configuration_Exception has been constructed without one.
@param message The exception's message String. If null the {@link
#ID class identification} will be used.
@param cause The exception's Throwable cause. If null no cause is
set in the exception object.
*/
public Configuration_Exception
(
String message,
Throwable cause
)
{
super ((message == null) ? ID : message);
if (cause != null)
initCause (cause);
}
/** Constructs a Configuration_Exception having a cause.
The exception message will be Configuration_Exception class ID.
@param cause The exception's Throwable cause. If null no cause is
set in the exception object.
@see #Configuration_Exception(String, Throwable)
*/
public Configuration_Exception
(
Throwable cause
)
{this (null, cause);}
/** Constructs a Configuration_Exception with a message.
@param message The exception's message String (may be null).
@see #Configuration_Exception(String, Throwable)
*/
public Configuration_Exception
(
String message
)
{this (message, null);}
/** Constructs a Configuration_Exception.
The exception will have the ID of this class as its message.
@see #Configuration_Exception(String, Throwable)
*/
public Configuration_Exception ()
{this (null, null);}
} // End of class
pirl-2.3.8/PIRL/Configuration/tests/ 0000755 0001750 0001750 00000000000 12052546520 017064 5 ustar mathieu mathieu pirl-2.3.8/PIRL/Configuration/tests/Makefile 0000644 0001750 0001750 00000000363 11033332335 020521 0 ustar mathieu mathieu # Makefile for Java classes
JPATH ?= .:../../..
JC ?= javac
.SUFFIXES: .java .class
.java.class:
${JC} -classpath ${JPATH} ${JFLAGS} $<
CLASSES = test_Configuration.class
all: classes
classes: ${CLASSES}
clean:
rm -f *.class
pirl-2.3.8/PIRL/Configuration/tests/test_Configuration.java 0000644 0001750 0001750 00000033747 11742733240 023615 0 ustar mathieu mathieu /* test_Configuration
PIRL CVS ID: test_Configuration.java,v 1.9 2012/04/16 06:05:20 castalia Exp
Copyright (C) 2003-2012 Arizona Board of Regents on behalf of the
Planetary Image Research Laboratory, Lunar and Planetary Laboratory at
the University of Arizona.
This file is part of the PIRL Java Packages.
The PIRL Java Packages are free software; you can redistribute them
and/or modify them under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
The PIRL Java Packages are distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see
The Configuration has its default "User", "Host", and "Classpath"
parameters removed and its Name is changed to the
Parser.CONTAINER_NAME so the enclosing Group will not be included
in the listing. A Listing of the Configuration is written to a
String. Then the original Name is restored.
@param configuration The Configuration to be listed.
@return The String containing the listing. If an Exception occurs
while generating the listing, the exception message will be
returned. If the lister encounters a Warning condition, the
warning message will be appended to the listing. If the configuration
is null, null will be returned.
*/
private static String Trimmed_Description
(
Configuration configuration
)
{
if (configuration == null)
return null;
// Remove DEFAULTS.
configuration.Remove ("User");
configuration.Remove ("Host");
configuration.Remove ("Classpath");
// Remove Environment variables.
configuration.Remove_Group (Configuration.ENVIRONMENT);
StringWriter
description = new StringWriter ();
Lister
lister = new Lister (description).Strict (false);
// Prevent the top level from being written.
String
name = configuration.Name ();
configuration.Name (Parser.CONTAINER_NAME);
try {lister.Write (configuration);}
catch (Exception exception)
{
// Restore the original name.
configuration.Name (name);
return exception.getMessage ();
}
// Restore the original name.
configuration.Name (name);
if (lister.Warning () != null)
description.getBuffer ()
.append ("\nWarning:\n")
.append (lister.Warning ().getMessage ());
return description.toString ();
}
}
pirl-2.3.8/PIRL/Conductor/ 0000755 0001750 0001750 00000000000 12052546525 015060 5 ustar mathieu mathieu pirl-2.3.8/PIRL/Conductor/Create_Pipeline 0000755 0001750 0001750 00000022712 11742733132 020037 0 ustar mathieu mathieu #!/usr/bin/perl
=pod
=head1 NAME
B
Each column of the matrix table is for a theater location. Each row
is for a Conductor name. Each cell contains the number of Conductors
having the row name operating on the theater location of the column
name.
@author Bradford Castalia, UA/PIRL
@version 1.15
*/
public class Conductor_Matrix_Model
extends AbstractTableModel
implements TableModelListener
{
/** Class identification name with source code version and date.
*/
public static final String
ID = "PIRL.Conductor.Maestro.Conductor_Matrix_Model (1.15 2012/04/16 06:04:11)";
public static final String
CONDUCTORS_COLUMN_NAME = "Conductors",
TOTALS_NAME = "Totals";
public static final int
RUN_TO_WAIT_STATE = Conductor_Table.RUN_TO_WAIT_STATE,
RUNNING_STATE = Conductor_Table.RUNNING_STATE,
POLLING_STATE = Conductor_Table.POLLING_STATE,
WAITING_STATE = Conductor_Table.WAITING_STATE,
HALTED_STATE = Conductor_Table.HALTED_STATE;
private Vector
@return The table column index for the Conductor identity. This will
be -1 if the identity is null, empty, or has a {@link
Conductor_Table_Model#Theater_Location(Message) Theater location}
not present in this table.
*/
public int Column
(
Message identity
)
{return findColumn (Conductor_Table_Model.Theater_Location (identity));}
/** Get the table row index for a Conductor identity.
@return The table row index for the Conductor identity. This will
be -1 if the identity is null, empty, or has a {@link
Conductor_Table_Model#Conductor_Name(Message) Conductor name}
not present in this table.
*/
public int Row
(
Message identity
)
{return findRow (Conductor_Table_Model.Conductor_Name (identity));}
public Count Count
(
int row,
int column
)
{
if (column > 0 &&
column <= getColumnCount () &&
row >= 0 &&
row < getRowCount ())
return Count_at (row, column);
return null;
}
public Count Count
(
Message identity
)
{
int
column = Column (identity);
if (column > 0)
{
int
row = Row (identity);
if (row >= 0)
return Count_at (row, column);
}
return null;
}
private Count Count_at
(
int row,
int column
)
{return Counts.get (row).get (--column);}
public int Total
(
int row,
int column
)
{
if (column > 0 &&
column <= getColumnCount () &&
row >= 0 &&
row < getRowCount ())
return Count_at (row, column).Counts[TOTAL];
return -1;
}
public int Total
(
String theater_location,
String conductor_name
)
{
int
column = findColumn (conductor_name);
if (column > 0)
{
int
row = findRow (theater_location);
if (row >= 0)
return Count_at (row, column).Counts[TOTAL];
}
return -1;
}
public int Total
(
Message identity
)
{
int
column = Column (identity);
if (column > 0)
{
int
row = Row (identity);
if (row >= 0)
return Count_at (row, column).Counts[TOTAL];
}
return -1;
}
protected Conductor_Matrix_Model Add
(
Message identity
)
{
if ((DEBUG & DEBUG_ADD) != 0)
System.out.println
(">>> Conductor_Matrix_Model.Add -" + identity);
if (identity != null)
{
String
theater_location,
conductor_name;
if ((theater_location = Conductor_Table_Model.Theater_Location (identity))
!= null &&
(conductor_name = Conductor_Table_Model.Conductor_Name (identity))
!= null)
{
int
column = findColumn (theater_location),
row = findRow (conductor_name);
Add_to (column, theater_location, row, conductor_name,
Conductor_Table_Model.Processing_State (identity));
// Update the table view.
if (column < 0)
fireTableStructureChanged ();
else
if (row < 0)
fireTableRowsInserted (row, row);
else
fireTableCellUpdated (row, column);
}
}
if ((DEBUG & DEBUG_ADD) != 0)
System.out.println
("<<< Conductor_Matrix_Model.Add");
return this;
}
protected void Add_to
(
int column,
String theater_location,
int row,
String conductor_name,
int processing_state
)
{
if ((DEBUG & DEBUG_ADD) != 0)
System.out.println
(">>> Add_to:" + NL
+" Column " + column + " - " + theater_location + NL
+" Row " + row + " - " + conductor_name + NL
+" State = " + processing_state);
boolean
changed = false;
if (column < 0)
{
// Add the new column.
column = getColumnCount ();
if ((DEBUG & DEBUG_ADD) != 0)
System.out.println
(" Adding column " + column);
for (int
rows = getRowCount (),
index = 0;
index < rows;
index++)
Counts.get (index).add (new Count ());
changed = Add_to_Theater_Names (theater_location);
}
if (row < 0)
{
// Add the new row.
row = getRowCount ();
if ((DEBUG & DEBUG_ADD) != 0)
System.out.println
(" Adding row " + row);
Vector
If the identity can be associated with a table cell its
Count values are {@link #Decrement(Count, Message) decremented}.
@param identity A Conductor identity Message.
*/
protected void Removing
(
Message identity
)
{
if ((DEBUG & DEBUG_REMOVE) != 0)
System.out.println
(">>> Conductor_Matrix_Model.Remove -" + identity);
int
row,
column;
if ((column = Column (identity)) > 0 &&
(row = Row (identity)) >= 0)
{
if ((DEBUG & DEBUG_REMOVE) != 0)
System.out.println
(" row " + row + ", column " + column);
Decrement (Counts.get (row).get (--column), identity);
//!!! Should check for an empty row or column and adjust accordingly.
fireTableCellUpdated (row, column);
}
if ((DEBUG & DEBUG_REMOVE) != 0)
System.out.println
("<<< Conductor_Matrix_Model.Remove");
}
/*==============================================================================
Count
*/
/** Index for arrays of processing state information.
*/
public static final int
RUNNING = 0,
POLLING = 1,
WAITING = 2,
HALTED = 3,
TOTAL = 4, // Must be last in the sequence.
UNKNOWN = 5; // Must be greater than TOTAL.
/** A Count contains table cell Conductor processing state count values.
A count of the number of Conductors in each processing state,
including the unknown state, is maintained plus the total number of
Conductors.
*/
public class Count
{
/** The Conductor processing state counts.
*/
public int
Counts[] = {0, 0, 0, 0, 0, 0};
public String toString ()
{return String.valueOf (Counts[TOTAL]);}
}
private void Increment
(
Count count,
Message identity
)
{Increment (count, Conductor_Table_Model.Processing_State (identity));}
private void Increment
(
Count count,
int processing_state
)
{
if (count == null)
return;
count.Counts[TOTAL]++;
switch (processing_state)
{
case RUN_TO_WAIT_STATE:
case RUNNING_STATE: count.Counts[RUNNING]++; break;
case POLLING_STATE: count.Counts[POLLING]++; break;
case WAITING_STATE: count.Counts[WAITING]++; break;
case HALTED_STATE: count.Counts[HALTED]++; break;
default: count.Counts[UNKNOWN]++;
}
if ((DEBUG & DEBUG_INCREMENTORS) != 0)
System.out.println
(">-< Increment: "
+ count.Counts[RUNNING] + "R "
+ count.Counts[POLLING] + "P "
+ count.Counts[WAITING] + "W "
+ count.Counts[HALTED] + "H "
+ count.Counts[UNKNOWN] + "U "
+ count.Counts[TOTAL] + "T");
}
private void Decrement
(
Count count,
Message identity
)
{Decrement (count, Conductor_Table_Model.Processing_State (identity));}
private void Decrement
(
Count count,
int processing_state
)
{
if (count == null)
return;
count.Counts[TOTAL]--;
switch (processing_state)
{
case RUN_TO_WAIT_STATE:
case RUNNING_STATE: count.Counts[RUNNING]--; break;
case POLLING_STATE: count.Counts[POLLING]--; break;
case WAITING_STATE: count.Counts[WAITING]--; break;
case HALTED_STATE: count.Counts[HALTED]--; break;
default: count.Counts[UNKNOWN]--;
}
if ((DEBUG & DEBUG_INCREMENTORS) != 0)
System.out.println
(">-< Decrement: "
+ count.Counts[RUNNING] + "R "
+ count.Counts[POLLING] + "P "
+ count.Counts[WAITING] + "W "
+ count.Counts[HALTED] + "H "
+ count.Counts[UNKNOWN] + "U "
+ count.Counts[TOTAL] + "T");
}
private void Adjust
(
Count count,
Message identity,
int previous_state
)
{
int
processing_state = Conductor_Table_Model.Processing_State (identity);
if (processing_state != previous_state);
{
Increment (count, processing_state);
Decrement (count, previous_state);
}
}
/*==============================================================================
TableModelListener
*/
public void tableChanged
(
TableModelEvent event
)
{
if (! (event instanceof Conductor_Table_Model_Event))
return;
if ((DEBUG & DEBUG_LISTENER) != 0)
System.out.println
(">>> Conductor_Matrix_Model.tableChanged");
Conductor_Table_Model
model = (Conductor_Table_Model)event.getSource ();
switch (event.getType ())
{
case TableModelEvent.INSERT:
if ((DEBUG & DEBUG_LISTENER) != 0)
System.out.println
(" INSERT: from "
+ event.getFirstRow () + " to "
+ event.getLastRow ());
for (int
index = event.getFirstRow ();
index <= event.getLastRow ();
index++)
Add (model.Identity (index));
break;
case TableModelEvent.UPDATE:
if ((DEBUG & DEBUG_LISTENER) != 0)
System.out.println
(" UPDATE: from "
+ event.getFirstRow () + " to "
+ event.getLastRow ());
if (event.getFirstRow () == TableModelEvent.HEADER_ROW ||
event.getLastRow () > getRowCount ())
/*
The changes to the source data model are non-specific.
Since source rows may have been added or removed the
entire matrix must be rebuilt.
*/
Rebuild (model);
else
{
Message
identity;
int
row,
column;
Count
count;
for (int
index = event.getFirstRow ();
index <= event.getLastRow ();
index++)
{
if ((identity = model.Identity (index)) != null &&
(column = Column (identity)) > 0 &&
(row = Row (identity)) >= 0 &&
(count = Count_at (row, column)) != null)
{
Adjust (count, identity,
((Conductor_Table_Model_Event)event).Processing_State ());
fireTableCellUpdated (row, column);
}
}
}
break;
case TableModelEvent.DELETE:
if ((DEBUG & DEBUG_LISTENER) != 0)
System.out.println
(" DELETE: from "
+ event.getFirstRow () + " to "
+ event.getLastRow ());
for (int
index = event.getFirstRow ();
index <= event.getLastRow ();
index++)
Removing (model.Identity (index));
break;
}
if ((DEBUG & DEBUG_LISTENER) != 0)
System.out.println
("<<< Conductor_Matrix_Model.tableChanged");
}
}
pirl-2.3.8/PIRL/Conductor/Maestro/Icons/ 0000755 0001750 0001750 00000000000 12052546524 017544 5 ustar mathieu mathieu pirl-2.3.8/PIRL/Conductor/Maestro/Icons/Exclamation.png 0000644 0001750 0001750 00000003273 11106472616 022522 0 ustar mathieu mathieu PNG
IHDR szz sRGB bKGD pHYs tIME ,2B ;IDATXŗM]g{ν7g棵ӒiڴiQ"HpƂ0ڍIq% X7*qW7nąą)bEE
iZrIfq;7D/\}9Ƀl>7=}
Ƕ3)
sx??39/m , /0}4O}[c_ӟ_5Y ^ۉ;At~/
@author Bradford Castalia - UA/PIRL
@version 1.6
@see Remote_Theater
*/
public class Remote_Management_Exception
extends RuntimeException
{
public static final String
ID = "PIRL.Conductor.Maestro.Remote_Management_Exception (1.6 2012/04/16 06:04:11)";
public Remote_Management_Exception
(
String message
)
{super (message);}
public Remote_Management_Exception
(
String message,
Throwable cause
)
{super (message, cause);}
public Remote_Management_Exception
(
Throwable cause
)
{super (cause);}
}
pirl-2.3.8/PIRL/Conductor/Maestro/Profile.java 0000644 0001750 0001750 00000156237 11742733133 020751 0 ustar mathieu mathieu /* Profile
PIRL CVS ID: Profile.java,v 1.35 2012/04/16 06:04:11 castalia Exp
Copyright (C) 2008-2012 Arizona Board of Regents on behalf of the
Planetary Image Research Laboratory, Lunar and Planetary Laboratory at
the University of Arizona.
This file is part of the PIRL Java Packages.
The PIRL Java Packages are free software; you can redistribute them
and/or modify them under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
The PIRL Java Packages are distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see
A Profile completely specifies the Conductor instances running, or
to be run, on a set of Theaters. A Profile may take the form of a
{@link Configuration} that can be {@link #Read(String) read} from
or {@link #Write(String) written} to and file.
A Theater definition is a list of one to three entries:
The Theater location is a required entry in the definition. It must
always be the first entry in the definition.
The Conductor name is not required in the definition. It may be the
second or third entry in the definition. A Theater definition witout
a Conductor name is a "discovery" definition: A connection is to be
made to the Theater and whatever Conductors are running there are to
be discovered. However, a Theater definition must not have a
Conductor name if it occurs within a Conductor definition, in which
case the Conductor name is implicitly the name of the Conductor
definition.
The Count is not required in the definition, but must not be present
if no Conductor name is present, unless the Theater definition occurs
within a Conductor definition. It may be the second or third entry in
the definition. The default Count is 1.
A Profile may contain zero or more Theater definitions. In a Profile
Configuration the Theater definitions are always contained in an
Assignment Parameter named "Theaters" with an Array Value that is a
list of one or more Theater locations, or a list of one or more
Theater definition Array Values.
Each Theater definition in the Profile is guaranteed to have a unique
combination of Theater location and Conductor name values. In a user
supplied Profile Configuration file, however, a Theater location and
Conductor name combination may occur in more than one Theater
definition. The Count of each duplicate location/name combination is
added to the Count of the initial definition. That is, Theater
definitions read from Configuration files are accumulated into a
consolidated list of unique definitions.
If a Conductor Theater definition with only a location entry is
duplicated, the duplicates are ignored. However, a definition with
the same location but that also contains a Conductor name causes the
location-only definition to be ignored.
A Theaters parameter in a user supplied Profile Configuration file
may occur at the top level of the file or within Conductor
definitions. A Theater definition within a Conductor definition must
not contain a Conductor name since this is implicitly the name of the
containing Conductor definition.
Example Profile Configuration Theater definitions:
A Conductor definition is an Aggregate (Group or Object) Parameter
that specifies the command line arguments used to instantiate a
Conductor at a Theater location. The name of the Aggregate is the
Conductor name used in a Theater definition. All Parameter Aggregates
in a Profile Configuration are taken to be Conductor definitions. The
parameters contained in a Conductor definition are all Assignments
with String values (except the Theaters parameter) and are all
optional:
If this parameter is not present it will be provided with the value
being the Conductor definition name.
If this parameter is not present the instantiated Conductor will use
its default Configuration source, which is expected to be the
"Conductor.conf" pathname.
If this parameter is not present the instantiated Conductor will use
the first entry in the Configuration Server parameter list.
If this parameter is not present the instantiated Conductor will use
the Catalog prefix of the Pipeline (catalog.pipeline) if present;
otherwise it will use the value of the "Catalog" name from the
Configuration Server parameter group, or the default "Catalog"
parameter in the Configuration.
A Profile may contain zero or more Conductor definitions. It is not
necessary that all Conductor definitions be referenced by a Conductor
name in a Theater definition. Any Conductor name in a Theater definition
for which a Conductor definition has not been provided will be satisfied
by a generic Conductor definition as if an emtpy group with the
Conductor name had been provided.
All Conductor definitions will be unique; Conductor definitions with
the same definition parameters must have different names. N.B.:
A Profile Configuration file should contain only one Conductor definition
Group (or Object) having a given name because when the Configuration is
ingested Groups with the same name will have their parameter contents
coalesced into a single Group; duplicate parameters names that are
encountered will result in an exception being thrown.
Example Profile Configuration Conductor definitions:
A Profile Configuration may be managed as separate files by taking
advantage of the "@Include" capability of a Configuration. For
example, sets of "standard" Conductor definitions may be maintained
in files separate from various files that contain Theater
definitions and "@Include" one or more of the standard Conductor
definition sets:
In this example the included files may have many Conductor
definitions, most of which are not used in any particular Theaters
Theater definitions list.
"@Include" may also be used to provide common parts of various
Coductor definitions by putting it inside the appropriate
Conductor definitions.
Profiles are used by the {@link Kapellmeister} application.
@author Michael Wendell and Bradford Castalia, UA/HiROC
@version 1.35
*/
public class Profile
{
/** Class identification name with source code version and date.
*/
public static final String
ID = "PIRL.Conductor.Maestro.Profile (1.35 2012/04/16 06:04:11)";
/** The name of a Profile {@link #Configuration() Configuration}.
*/
public static final String
PROFILE_NAME = "Profile";
/** The Profile Configuration parameter name for a list of Theater
definitions.
*/
public static final String
THEATERS_PARAMETER_NAME = "Theaters";
/** The size of a complete Theater definition Vector.
*/
public static final int
THEATER_DEFINITION_SIZE = 3;
/** The index of the Theater location String in a theater definition Vector.
*/
public static final int
THEATER_LOCATION_INDEX = 0;
/** The index of the Conductor name String or Conductor_Definition
in a theater definition Vector.
*/
public static final int
CONDUCTOR_NAME_INDEX = 1;
/** The index of the Conductor count Integer in a theater definition Vector.
*/
public static final int
CONDUCTOR_COUNT_INDEX = 2;
/** Theater Conductor name entry when no Conductor_Definition is provided.
*/
public static final String
NO_CONDUCTOR_DEFINITION = null;
/** The name of the Conductor definition parameter that specifies the
pipeline to be processed.
*/
public static final String
PIPELINE_PARAMETER_NAME
= Conductor_Definition.PIPELINE_PARAMETER_NAME;
private Vector
Any parameters remaining after the source has been {@link #Read(String)
read} will be held in the {@link #Unprocessed_Source_Parameters()
unprocessed source Configuration}.
@param source A Configuration source String. This may be a file
pathname or a URL.
@throws Configuration_Exception If there was a problem with the source
Configuration syntax.
*/
public Profile
(
String source
)
throws
Configuration_Exception,
PVL_Exception
{
if ((DEBUG & DEBUG_CONSTRUCTOR) != 0)
System.out.println
(">>> Profile: " + source);
Read (source);
if ((DEBUG & DEBUG_CONSTRUCTOR) != 0)
System.out.println
("<<< Profile");
}
/** Construct a Profile from Theater and Conductor definitions.
@param theater_definitions A List of Theater definitions.
@param conductor_definitions A List of Conductor_Definitions.
@throws IllegalArgumentException If there was a problem creating the
Profile.
@see #Add(List, List)
*/
public Profile
(
List
Theater and Conductor definitions found in the Configuration are
added to the definitions currently in this Profile.
@param source A Configuration source String. This may be a file
pathname or a URL.
@return This Profile.
@throws Configuration_Exception If the source can not be found or parsed
as valid PVL or the contents do not conform to valid Profile
syntax.
@see #Read(Configuration)
*/
public Profile Read
(
String source
)
throws Configuration_Exception
{
if ((DEBUG & DEBUG_READ) != 0)
System.out.println
(">>> Profile.Read: " + source);
Source_Parameters = new Configuration ();
try
{
Source_Parameters.Defaults (false);
Source_Parameters.Configure (source);
}
catch (Configuration_Exception exception)
{
throw new Configuration_Exception (ID + NL
+ "Could not read a Profile from the source -" + NL
+ source + NL
+ exception.getMessage ());
}
return Read (Source_Parameters);
}
/** Read Theater and Conductor definitions from a Configuration.
Theater and Conductor definitions found in the Configuration are
added to the definitions currently in this Profile. Only {@link
#THEATERS_PARAMETER_NAME} Assignment parameters are used as Theater
definitions. All Aggregate parameters are taken to be Conductor
definitions.
N.B.: The Theater and Conductor definitions found in the
Configuration are removed from the Configuration leaving only the
{@link #Unprocessed_Source_Parameters() unprocessed source parameters}
in the original Configuration.
@param configuration A Configuration. If null nothing is done.
@return This Profile.
@throws Configuration_Exception If the Configuration Theater or
Conductor definition contents do not conform to valid Profile
syntax.
*/
public Profile Read
(
Configuration configuration
)
throws Configuration_Exception
{
if ((DEBUG & DEBUG_READ) != 0)
System.out.println
(">>> Profile.Read: Configuration -" + NL
+ configuration);
if ((Source_Parameters = configuration) == null)
{
if ((DEBUG & DEBUG_READ) != 0)
System.out.println
("<<< Profile.Read: Configuration");
return this;
}
// Conductor Groups.
if ((DEBUG & DEBUG_READ) != 0)
System.out.println
(" Profile.Read: Finding Conductor groups");
Parameter
parameter;
while ((parameter = Source_Parameters.Find (Parameter.AGGREGATE)) != null)
{
if ((DEBUG & DEBUG_READ) != 0)
System.out.println
(" Profile.Read: Conductor definition -" + NL
+ parameter.Description ());
Parameter
invalid = parameter.Find (Parameter.AGGREGATE);
if (invalid != null)
throw new Configuration_Exception (ID + NL
+ "Invalid Profile syntax in the Configuration source -" + NL
+ configuration.Source () + NL
+ "The \"" + parameter.Name () + "\" Conductor definition "
+ "contains the \"" + invalid.Name ()
+ "\" Aggregate parameter.");
else
{
try {Add_Conductor_Definition (parameter);}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(exception.getMessage () + NL
+ "Problem reading the Configuration source -" + NL
+ configuration.Source ());
}
}
Source_Parameters.Remove (parameter);
}
// Theater definitions.
if ((DEBUG & DEBUG_READ) != 0)
System.out.println
(" Profile.Read: Finding Theaters");
if ((parameter = Source_Parameters.Find
(Parameter.Absolute_Pathname (THEATERS_PARAMETER_NAME),
Parameter.ASSIGNMENT))
!= null)
{
// Theaters Value.
if ((DEBUG & DEBUG_READ) != 0)
System.out.println
(" Profile.Read: Theater definition -" + NL
+ parameter.Description ());
try {Add_Theater_Definitions (parameter.Value ());}
catch (PVL_Exception exception)
{
throw new Configuration_Exception
(exception.getMessage () + NL
+ "Problem reading the Configuration source -" + NL
+ configuration.Source ());
}
Source_Parameters.Remove (parameter);
}
if (Source_Parameters.List_Size () == 0)
Source_Parameters = null;
if ((DEBUG & DEBUG_READ) != 0)
System.out.println
(" Profile.Read: Remaining parameters - "
+ ((Source_Parameters == null) ? "null" : (NL
+ Source_Parameters.Description ())) + NL
+ NL
+" Profile -" + NL
+ toString () + NL
+"<<< Profile.Read");
return this;
}
/** Get unprocessed Configuration parameters.
@return A Configuration containing any parameters remaining after a
Configuration source was {@link #Read(Configuration) read}. This
will be null if there were no unprocessed parameters.
*/
public Configuration Unprocessed_Source_Parameters ()
{return Source_Parameters;}
/** Write the Profile to a {@link #Configuration() Configuration} file.
If the Profile is empty nothing is written.
@param pathname The file pathname String. If null or empty
nothing is done.
@return This Profile.
@throws Configuration_Exception If there was a problem creating a
Configuration for this Profile.
@throws IOException If there was a problem writing the file.
@see #Write(OutputStream)
*/
public Profile Write
(
String pathname
)
throws
Configuration_Exception,
IOException
{
if (pathname == null ||
pathname.length () == 0)
return this;
OutputStream
output_stream = null;
try {output_stream = new FileOutputStream (pathname);}
catch (IOException exception)
{
throw new IOException (ID + NL
+ "Could not write the Profile to -" + NL
+ new File (pathname).getAbsolutePath () + NL
+ exception.getMessage ());
}
try {Write (output_stream);}
catch (Configuration_Exception exception)
{
throw new Configuration_Exception
(exception.getMessage () + NL
+ "File pathname: " + new File (pathname).getAbsolutePath ());
}
catch (IOException exception)
{
throw new IOException
(exception.getMessage () + NL
+ "File pathname: " + new File (pathname).getAbsolutePath ());
}
return this;
}
/** Write the Profile to an OutputStream.
A {@link #Configuration() configuration} is created from the current
Profile contents and this is {@link Configuration#Write(OutputStream)
written} to the OutputStream.
If the Profile is empty nothing is written.
@param output_stream An OutputStream where the Profile Configuration
is to be written. If null nothing is done.
@return This Profile.
@throws Configuration_Exception If there was a problem creating a
Configuration for this Profile.
@throws IOException If there was a problem writing the file.
*/
public Profile Write
(
OutputStream output_stream
)
throws
Configuration_Exception,
IOException
{
if (output_stream == null)
return this;
Configuration
configuration = null;
try {configuration = Configuration ();}
catch (Configuration_Exception exception)
{
throw new Configuration_Exception (ID + NL
+ exception.getMessage () + NL
+ "Problem creating the Profile Configuration to write.");
}
if (configuration.List_Size () != 0)
{
try
{
configuration.Name (Parser.CONTAINER_NAME);
((Parameter)configuration.List ().get (0))
.Comments
("Profile of Theater and Conductor definitions." + NL
+ NL
+ Stage_Manager.DATE_FORMAT.format (new Date ()) + NL
+ "Generated by:" + NL
+ ID);
configuration.Write (output_stream);
}
catch (PVL_Exception exception)
{
throw new Configuration_Exception (ID + NL
+ exception.getMessage () + NL
+ "Problem writing the Profile.");
}
catch (IOException exception)
{
throw new IOException (ID + NL
+ exception.getMessage () + NL
+ "Problem writing the Profile.");
}
}
return this;
}
/** Get the Profile as a Configuration.
@return A Configuration containing the Profile definition parameters.
The {@link Configuration#Name() Name} of the Configuration will
be the {@link #PROFILE_NAME}.
@throws Configuration_Exception If there was a problem creating the
Configuration
*/
public Configuration Configuration ()
throws
Configuration_Exception
{
int
array_type = Value.Default_Array_Type (Value.SEQUENCE);
Configuration
configuration = new Configuration ((Parameter)null);
if (Theater_Definitions.size () > 0)
{
// Get a Theater definitions list sorted on the location.
Vector
The current contents of the Profile are converted to a {@link
#Configuration() Configuration} from which a PVL {@link
Configuration#Description() description} is obtained.
@return A PVL String description of the Profile. This will be null
if the {@link #Configuration() Configuration} description
could not be generated.
*/
public String toString ()
{
try {return Configuration ().Description ();}
catch (Exception exception) {}
return null;
}
/*==============================================================================
Manipulators
*/
/** Adds Theater and Conductor definitions to the Profile.
@param theater_definitions A List of Theater definitions.
@param conductor_definitions A List of Conductor_Definitions.
@throws IllegalArgumentException If the arguments are not one
List of valid Theater definitions and one List of valid
Conductor_Definitions.
*/
public Profile Add
(
List
The Theater definition will have as a Conductor name the
{@link Conductor_Table_Model#Conductor_Name(Message) Conductor name}
obtained from the Conductor definition, and it will have a Conductor
count of 1.
@param theater_location A Theater location String. If null or
empty nothing is done.
@param conductor_definition A Conductor definition Message. If null
nothing is done.
@return This Profile.
@throws IllegalArgumentException If the Conductor definition
conflicts with an existing definition.
@see #Add_Theater_Definition(String)
@see #Add_Conductor_Definition(Message)
*/
public Profile Add
(
String theater_location,
Message conductor_definition
)
throws IllegalArgumentException
{
if (theater_location == null ||
theater_location.length () == 0 ||
conductor_definition == null)
return this;
Add_Conductor_Definition (conductor_definition);
Vector
Usage
Description
Options
-[No_]Tiles
Tiles segment parameters are to be included (or not).
The default is not to include tile segment parameters.
-Gui
The information PVL is provided in a GUI viewer. The default is to
provide a terminal listing.
-Find <parameter>
The named parameter is listed. This option may be repeated to obtain
a listing of all parameters specified.
-Pattern <regex>
The parameters with names that match the regular expression are
listed. This option may also be repeated.
Usage
Description
Options
-[No_]Tiles
Tiles segment parameters are to be included (or not).
The default is not to include tile segment parameters.
-Gui
The information PVL is provided in a GUI viewer. The default is to
provide a terminal listing.
-Find <parameter>
The named parameter is listed. This option may be repeated to obtain
a listing of all parameters specified.
-Pattern <regex>
The parameters with names that match the regular expression are
listed. This option may also be repeated.
Exit Status
1 - Command line syntax problem
2 - I/O Exception while attemping to read the source file
3 - No information was found
4 - An error occurred in assembing the PVL parameters for the JP2 information
5 - The source file does not have the required JP2 contents
longitude = Center_Longitude + x / (R * cos (Center_Latitude))
where R is the {@link Projection#Local_Radius(double) radius} of the
body at the Center_Latitude.
latitude = y / R
DDDd MMm SS.SSSs
where DDD is integer degrees, MM is integer minutes in the range 0 to
59, and SS.SSS is seconds with fractional seconds in the range 0.0 to
59.999 For example, 206.291 degrees is represented as "206d 17m
27.600s". N.B.: A fixed field format is used in which leading
spaces and trailing zeros are used to each value occurs at a specific
location in the String representation.
HHh MMm SS.SSSs
where HH is integer hours in the range 0 to 24, MM is integer minutes
in the range 0 to 59, and SS.SSS is seconds with fractional seconds
in the range 0.0 to 59.999 For example, 206.291 degrees is
represented as "13h 45m 9.840s". N.B.: A fixed field format
is used in which leading spaces and trailing zeros are used to each
value occurs at a specific location in the String representation.
E = sqrt (1 - polar_radius**2 / equitorial_radius**2)
R = Re * Rp / sqrt (a**2 + b**2)
where:
Re = {@link Projection#Equitorial_Radius() Equitorial_Radius}
Rp = {@link Projection#Polar_Radius() Polar_Radius}
a = Re * sin (latitude)
b = Rp * cos (latitude)
*/
public static final Parameter
Defaults = new Parameter (DEFAULTS);
static
{
try
{
Defaults.Add (new Parameter (CLASSPATH)
.Value (System.getProperty ("java.class.path")));
Defaults.Add (new Parameter (USER)
.Value (System.getProperty ("user.name")));
Defaults.Add (new Parameter (HOST)
.Value ("localhost"));
}
catch (PVL_Exception exception) {/* This shouldn't happen. */}
}
/** The default automatic {@link #Defaults(boolean) Defaults} state.
*/
public static boolean
Defaults_Default = true;
private boolean
Include_Defaults = Defaults_Default;
private static Class
Relative_to_Class = null;
/** The first duplicate parameter in the list gets preference when
coalescing.
Set (new Parameter (parameter), replace);
INCLUDE_START:source
1 - Command line syntax problem
2 - Unable to assemble the configuration
3 - The source file could not be found
*/
public static void main
(
String[] arguments
)
{
if (arguments.length == 0)
Usage ();
Configuration
configuration = null;
String
source = null;
Vector
find_pathnames = new Vector ();
boolean
quiet = false,
case_sensitive = false,
pattern_match = false;
for (int count = 0;
count < arguments.length;
count++)
{
if (arguments[count].length () > 1 &&
arguments[count].charAt (0) == '-')
{
switch (arguments[count].charAt (1))
{
case 'Q': // Quiet
case 'q':
quiet = true;
case 'F': // Find
case 'f':
if (++count == arguments.length ||
arguments[count].charAt (0) == '-')
{
System.out.println
("Missing parameter pathname.");
Usage ();
}
find_pathnames.add (arguments[count]);
break;
case 'C': // Case_sensitive
case 'c':
case_sensitive = true;
pattern_match = false;
break;
case 'N': // Not_case_sensitive
case 'n':
case_sensitive = false;
break;
case 'P': // Pattern
case 'p':
pattern_match = true;
case_sensitive = false;
break;
case 'V': // Version
case 'v':
System.out.println (ID);
System.exit (0);
default:
System.out.println
("Unknown option: " + arguments[count]);
case 'H': // Help
case 'h':
Usage ();
}
}
else
{
if (source != null)
{
System.out.println
("More than one Configuration source specified -" + NL
+" First source: " + source + NL
+" Second source: " + arguments[count]);
Usage ();
}
source = arguments[count];
}
}
if (source == null)
{
System.out.println ("No Configuration source specified.");
Usage ();
}
try
{
Include_Tracing_Default = true;
try
{
if (source.equals ("-"))
configuration = new Configuration (System.in);
else
configuration = new Configuration (source);
}
catch (IllegalArgumentException exception)
{
System.err.println
("Could not find the configuration source file: " + source);
System.exit (3);
}
configuration.Add_Environment ();
if (find_pathnames.isEmpty ())
System.out.println (configuration.Description ());
else
{
Iterator
pathnames = find_pathnames.iterator ();
String
parent_pathname,
comments;
Parameter
parameter,
test_parameter = new Parameter ();
Selection
selection = new Selection ();
selection.Name (true);
selection.Specific (case_sensitive);
selection.Pattern_Match (pattern_match);
Lister
lister = new Lister ().Indent_Arrays (false);
while (pathnames.hasNext ())
{
test_parameter.Name ((String)pathnames.next ());
parameter = null;
while ((parameter = configuration.Find
(test_parameter, selection, parameter)) != null)
{
comments = parameter.Comments ();
parameter.Comments (null);
try
{
if (! quiet &&
comments != null)
lister.Write_Comments (comments);
parent_pathname = Parent_Pathname (Pathname (parameter));
if (parent_pathname != null)
System.out.print (parent_pathname);
System.out.print (Path_Delimiter ());
parameter.Write (lister);
}
catch (PVL_Exception exception)
{
System.err.println
("PVL_Exception while listing parameter \""
+ parameter.Path_Name () + '"' + NL
+ exception.getMessage ());
}
catch (IOException exception)
{
System.err.println
("IOException while listing parameter \""
+ parameter.Path_Name () + '"' + NL
+ exception.getMessage ());
}
}
}
}
}
catch (Configuration_Exception exception)
{
System.err.println
(NL
+"Configuration Exception:" + NL
+ exception.getMessage ());
System.exit (2);
}
System.exit (0);
}
/** Prints the command line usage syntax.
Usage: Configuration <Options> <source>
Options -
-Query | -Find <pathname>
[-Not_]Case_sensitive
-Pattern
Theater definitions
# Single Theater location.
Theaters = host
Theaters = host:1234
Theaters = (host)
# Multiple Theater locations.
Theaters = (host_1, host_2, host_3, host_3:1234)
# Single Theater definition.
Theaters = ((host, name, 1))
Theaters = ((host, name))
# Multiple Theater definitions.
Theaters = ((host_1, name), (host_2, name, 2), (host_3, name_3, 3))
Theaters =
(
host_1:1234,
(host_2:1234, name),
(host_3:1234, name_3, 3)
)
Conductor definitions
# A generic Conductor definition.
Group = name
End_Group
# Simple Conductor definitions.
Group = name
Pipeline = pipeline
End_Group
Group = name_1
Pipeline = pipeline
Configuration = config_pathname_1
End_Group
Group = name_2
Pipeline = pipeline_2
Configuration = config_pathname_2
End_Group
# Complete Conductor definition.
Group = name
Pipeline = pipeline
Configuration = /an/absolute/pathname
Server = server_name
Catalog = catalog_name
End_Group
# Conductor definition with Theater definitions.
Group = pipeline
Theaters = ((host_1), (host2, 2), (host_3, 3))
Configuration = http://config.host/pathname/to/file
End_Group
# Theater definitions.
Theaters =
(
# Using standard Conductor definitions.
(host_1, standard_1),
(host_2, standard_2),
# Using special processing Conductor definitions.
(host_1, special_1),
(host_2, special_2)
# Custom Conductor definitions.
(host_1, custom_1),
# Local Conductor definition.
(host_2, local, 3)
)
# Standard Conductor definitions.
@Include = /Conductor/definitions/repository/Standard.defs
# Special processing Conductor definitions.
@Include = /Conductor/definitions/repository/Special_Processing.defs
# Custom Conductor definitions.
@Include = Custom_Conductor.defs
# Local Conductor definition.
Group = local
Configuration = /an/absolute/pathname
End_Group