com.sun.j3d.utils.geometry.compression

## Class CompressedGeometryFile

- java.lang.Object
- - com.sun.j3d.utils.geometry.compression.CompressedGeometryFile

-     public class CompressedGeometryFile
      extends java.lang.Object

  This class provides methods to read and write compressed geometry resource files. These files usually end with the .cg extension and support sequential as well as random access to multiple compressed geometry objects.
  Since:
    Java 3D 1.5

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CompressedGeometryFile(java.io.RandomAccessFile file)` Construct a new CompressedGeometryFile instance associated with a currently open RandomAccessFile.
    `CompressedGeometryFile(java.lang.String file)` Construct a new CompressedGeometryFile instance associated with the specified file.
    `CompressedGeometryFile(java.lang.String file, boolean rw)` Construct a new CompressedGeometryFile instance associated with the specified file.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()` Delete all compressed objects from this instance.
    `void` | `close()` Release the resources associated with this instance.
    `protected void` | `finalize()` Release file resources when this object is garbage collected.
    `int` | `getCurrentIndex()` Return the current object index associated with this instance.
    `java.lang.String` | `getFileName()` Return a string containing the file name associated with this instance or null if there is none.
    `int` | `getMajorVersionNumber()` Return the major version number of the most recent compressor used to compress any of the objects in this instance.
    `int` | `getMinorMinorVersionNumber()` Return the subminor version number of the most recent compressor used to compress any of the objects in this instance.
    `int` | `getMinorVersionNumber()` Return the minor version number of the most recent compressor used to compress any of the objects in this instance.
    `int` | `getObjectCount()` Return the number of compressed objects in this instance.
    `CompressedGeometryData[]` | `read()` Read all compressed geometry objects contained in the instance.
    `CompressedGeometryData` | `read(int index)` Read the compressed geometry object at the specified index.
    `CompressedGeometryData` | `readNext()` Read the next compressed geometry object in the instance.
    `void` | `write(CompressedGeometryData.Header cgh, byte[] geometry)` Add a buffer of compressed geometry data to the end of the resource.
    `void` | `write(CompressedGeometryData cg)` Add a compressed geometry node component to the end of the instance.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CompressedGeometryFile

          public CompressedGeometryFile(java.lang.String file)
                                 throws java.io.IOException

      Construct a new CompressedGeometryFile instance associated with the specified file. An attempt is made to open the file with read-only access; if this fails then a FileNotFoundException is thrown.
      Parameters:
        `file` - path to the compressed geometry resource file
      Throws:
        `java.io.FileNotFoundException` - if file doesn't exist or cannot be read
        `java.lang.IllegalArgumentException` - if the file is not a compressed geometry resource file
        `java.io.IOException` - if there is a header or directory read error

    - #### CompressedGeometryFile

          public CompressedGeometryFile(java.lang.String file,
                                boolean rw)
                                 throws java.io.IOException

      Construct a new CompressedGeometryFile instance associated with the specified file.
      Parameters:
        `file` - path to the compressed geometry resource file
        `rw` - if true, opens the file for read and write access or attempts to create one if it doesn't exist; if false, opens the file with read-only access
      Throws:
        `java.io.FileNotFoundException` - if file doesn't exist or access permissions disallow access
        `java.lang.IllegalArgumentException` - if the file is not a compressed geometry resource file
        `java.io.IOException` - if there is a header or directory read error

    - #### CompressedGeometryFile

          public CompressedGeometryFile(java.io.RandomAccessFile file)
                                 throws java.io.IOException

      Construct a new CompressedGeometryFile instance associated with a currently open RandomAccessFile.
      Parameters:
        `file` - currently open RandomAccessFile
      Throws:
        `java.lang.IllegalArgumentException` - if the file is not a compressed geometry resource file
        `java.io.IOException` - if there is a header or directory read error

  - ### Method Detail

    - #### clear

          public void clear()
                     throws java.io.IOException

      Delete all compressed objects from this instance. This method may only be called after successfully creating a CompressedGeometryFile instance with read-write access, so a corrupted or otherwise invalid resource must be removed manually before it can be rewritten. The close() method must be called sometime after invoking clear() in order to write out the new directory structure.
      Throws:
        `java.io.IOException` - if clear fails

    - #### getFileName

          public java.lang.String getFileName()

      Return a string containing the file name associated with this instance or null if there is none.
      Returns:
        file name associated with this instance or null if there is none

    - #### getMajorVersionNumber

          public int getMajorVersionNumber()

      Return the major version number of the most recent compressor used to compress any of the objects in this instance.
      Returns:
        major version number

    - #### getMinorVersionNumber

          public int getMinorVersionNumber()

      Return the minor version number of the most recent compressor used to compress any of the objects in this instance.
      Returns:
        minor version number

    - #### getMinorMinorVersionNumber

          public int getMinorMinorVersionNumber()

      Return the subminor version number of the most recent compressor used to compress any of the objects in this instance.
      Returns:
        subminor version number

    - #### getObjectCount

          public int getObjectCount()

      Return the number of compressed objects in this instance.
      Returns:
        number of compressed objects

    - #### getCurrentIndex

          public int getCurrentIndex()

      Return the current object index associated with this instance. This is the index of the object that would be returned by an immediately following call to the readNext() method. Its initial value is 0; -1 is returned if the last object has been read.
      Returns:
        current object index, or -1 if at end

    - #### readNext

          public CompressedGeometryData readNext()
                                          throws java.io.IOException

      Read the next compressed geometry object in the instance. This is initially the first object (index 0) in the instance; otherwise, it is whatever object is next after the last one read. The current object index is incremented by 1 after the read. When the last object is read the index becomes invalid and an immediately subsequent call to readNext() returns null.
      Returns:
        a CompressedGeometryData node component, or null if the last object has been read
      Throws:
        `java.io.IOException` - if read fails

    - #### read

          public CompressedGeometryData[] read()
                                        throws java.io.IOException

      Read all compressed geometry objects contained in the instance. The current object index becomes invalid; an immediately following call to readNext() will return null.
      Returns:
        an array of CompressedGeometryData node components.
      Throws:
        `java.io.IOException` - if read fails

    - #### read

          public CompressedGeometryData read(int index)
                                      throws java.io.IOException

      Read the compressed geometry object at the specified index. The current object index is set to the subsequent object unless the last object has been read, in which case the index becomes invalid and an immediately following call to readNext() will return null.
      Parameters:
        `index` - compressed geometry object to read
      Returns:
        a CompressedGeometryData node component
      Throws:
        `java.lang.IndexOutOfBoundsException` - if object index is out of range
        `java.io.IOException` - if read fails

    - #### write

          public void write(CompressedGeometryData cg)
                     throws java.io.IOException

      Add a compressed geometry node component to the end of the instance. The current object index becomes invalid; an immediately following call to readNext() will return null. The close() method must be called at some later time in order to create a valid compressed geometry file.
      Parameters:
        `cg` - a compressed geometry node component
      Throws:
        `CapabilityNotSetException` - if unable to get compressed geometry data from the node component
        `java.io.IOException` - if write fails

    - #### write

          public void write(CompressedGeometryData.Header cgh,
                   byte[] geometry)
                     throws java.io.IOException

      Add a buffer of compressed geometry data to the end of the resource. The current object index becomes invalid; an immediately following call to readNext() will return null. The close() method must be called at some later time in order to create a valid compressed geometry file.
      Parameters:
        `cgh` - a CompressedGeometryData.Header object describing the data.
        `geometry` - the compressed geometry data
      Throws:
        `java.io.IOException` - if write fails

    - #### close

          public void close()

      Release the resources associated with this instance. Write out final header and directory if contents were updated. This method must be called in order to create a valid compressed geometry resource file if any updates were made.

    - #### finalize

          protected void finalize()

      Release file resources when this object is garbage collected.
      Overrides:
        `finalize` in class `java.lang.Object`

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.