oracle.ide.net
Class JarIndex

java.lang.Object
  oracle.ide.net.JarIndex

public final class JarIndex
extends java.lang.Object

Indexes the table of contents of a JAR or ZIP file.

It is important to understand that the return values of all the methods of this class are a reflection of the state of the JAR index at the moment the method was called. If the JAR file subsequently changes on disk, the return value of any previous calls may no longer be accurate. In particular, this means that the return values of multiple calls are not guaranteed to be consistent, because the JAR file may have changed in between the calls. The only way to obtain consistent results for multiple JAR entries is with the visit(oracle.ide.net.JarIndex.Visitor) method. This method holds an open file handle while iterating the JAR entries, preventing any external modification of the JAR while the entries are being visited.

Nested Class Summary

static interface

JarIndex.Visitor Visits entries in this index.

Method Summary

static void	closeUserJars() Closes all open user JARs, and prevents them from being left open until leaveJarsOpen() is called.
int	dirEntryIndex(java.lang.String entryName) Deprecated. Use isDirectory(String) to determine if an entry is a directory, or visit(Visitor) to iterate the index entries. The index returned by this method may become invalid if the JAR file changes on disk.
int	entryIndex(java.lang.String entryName) Deprecated. Use visit(Visitor) to iterate the index entries. The index returned by this method may become invalid if the JAR file changes on disk.
boolean	exists(java.lang.String entryName) Checks for the existance of an entry with the given name.
static void	flushCache()
byte[]	getBytes(java.lang.String entryName) Returns a byte array with the uncompressed data corresponding to entryName.
long	getCompressedSize(java.lang.String entryName) Returns the compressed size of a JAR entry.
java.lang.String[]	getEntries() Fetch a list of all entry names.
JarIndexEntry	getEntryAt(int i) Deprecated. Use visit(Visitor) to iterate the index entries. The index passed to this method may be invalid if the JAR file has changed on disk.
java.lang.String	getEntryNameAt(int i) Deprecated. Use visit(Visitor) to iterate the index entries. The index passed to this method may be invalid if the JAR file has changed on disk.
static JarIndex	getInstance(java.net.URL jarFileURL) Get a JarIndex instance.
int	getNumEntries() Deprecated. Use visit(Visitor) to iterate the index entries, or isEmpty() to determine if the JAR index is empty. The number of entries returned by this method may become invalid if the JAR file changes on disk, so any operations assuming this value is correct may fail.
long	getSize(java.lang.String entryName) Returns the uncompressed size of the specified entry.
long	getTimestamp() Get the timestamp of the index.
long	getTimestamp(java.lang.String entryName) Get the timestamp of a JAR entry.
boolean	isDirectory(java.lang.String entryName) Determines whether an entry exists and is a direcory.
boolean	isEmpty() Determines whether this JAR index is currently empty.
static void	leaveJarsOpen() If caching is enabled, a call to this method allows JarIndexes to keep JAR files open for a period of time before closing them.
java.lang.String[]	list(java.lang.String dirEntryName)
boolean	lockJarFile() Locks the JAR file handle open for this index.
java.io.InputStream	openInputStream(java.lang.String entryName) Opens an input stream for the specified entryName.
static void	runWhileClosed(java.lang.Runnable r) Run a task while the JAR indexes corresponding to user JARs are locked closed.
static void	uncache(java.net.URL jarFileURL) Remove any cached index for a JAR file.
void	unlockJarFile() Unlocks the JAR file handle so the JAR can be closed.
void	visit(JarIndex.Visitor visitor) Visit the entries in this index.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static JarIndex getInstance(java.net.URL jarFileURL)

Get a JarIndex instance.

Parameters:

jarFileURL - the URL of the JAR file

Returns:

the JAR index

uncache

public static void uncache(java.net.URL jarFileURL)

Remove any cached index for a JAR file.

Parameters:

jarFileURL - the URL of the JAR File

lockJarFile

public boolean lockJarFile()

Locks the JAR file handle open for this index. Callers must ensure that unlockJarFile() is called when they are finished with the JAR. This can be used when numerous entries will be accessed within the JAR during a specific interval. Note that locking many JARs open can cause the process to run out of file handles, and prevents the user from being able to modify or delete the JAR files. JAR files should only be locked open for as long as is necessary.

Returns:

true if the file wasn't locked to begin with.

unlockJarFile

public void unlockJarFile()

Unlocks the JAR file handle so the JAR can be closed.

visit

public void visit(JarIndex.Visitor visitor)
           throws java.io.IOException

Visit the entries in this index.

Parameters:

visitor - the visitor

Throws:

java.io.IOException - if the JAR cannot be read

isEmpty

public boolean isEmpty()

Determines whether this JAR index is currently empty.

Returns:

true if the JAR index is empty, false otherwise

dirEntryIndex

@Deprecated
public int dirEntryIndex(java.lang.String entryName)

Deprecated. Use isDirectory(String) to determine if an entry is a directory, or visit(Visitor) to iterate the index entries. The index returned by this method may become invalid if the JAR file changes on disk.

entryIndex

@Deprecated
public int entryIndex(java.lang.String entryName)

Deprecated. Use visit(Visitor) to iterate the index entries. The index returned by this method may become invalid if the JAR file changes on disk.

closeUserJars

public static void closeUserJars()

Closes all open user JARs, and prevents them from being left open until leaveJarsOpen() is called. Great care must be taken when calling this method to avoid deadlock. This method should never be called while holding onto any other locks, such as Node locks. Doing so would cause deadlock with other threads that use the JAR indexes.

This method is useful for situations where JAR files might need to be deleted or replaced while JDeveloper is running.

It is strongly recommended that runWhileClosed(Runnable) be used instead of this method.

See Also:

leaveJarsOpen(), runWhileClosed(Runnable)

leaveJarsOpen

public static void leaveJarsOpen()

If caching is enabled, a call to this method allows JarIndexes to keep JAR files open for a period of time before closing them. This is the default behavior, unless closeUserJars() was called. It is strongly recommended that runWhileClosed(Runnable) be used instead of this method.

See Also:

leaveJarsOpen(), runWhileClosed(Runnable)

getNumEntries

@Deprecated
public int getNumEntries()

Deprecated. Use visit(Visitor) to iterate the index entries, or isEmpty() to determine if the JAR index is empty. The number of entries returned by this method may become invalid if the JAR file changes on disk, so any operations assuming this value is correct may fail.

Returns the number of entries in the index.

getEntryAt

@Deprecated
public JarIndexEntry getEntryAt(int i)

Deprecated. Use visit(Visitor) to iterate the index entries. The index passed to this method may be invalid if the JAR file has changed on disk.

Throws:

java.lang.IndexOutOfBoundsException - if the specified index is less than 0 or greater than or equal to the number of indexed entries.

getEntryNameAt

@Deprecated
public java.lang.String getEntryNameAt(int i)

Deprecated. Use visit(Visitor) to iterate the index entries. The index passed to this method may be invalid if the JAR file has changed on disk.

Throws:

java.lang.IndexOutOfBoundsException - if the specified index is less than 0 or greater than or equal to the number of indexed entries.

getEntries

public java.lang.String[] getEntries()

Fetch a list of all entry names.

Returns:

an array of all entry names.

getSize

public long getSize(java.lang.String entryName)

Returns the uncompressed size of the specified entry. If the entry does not exist, -1 is returned.

list

public java.lang.String[] list(java.lang.String dirEntryName)

openInputStream

public java.io.InputStream openInputStream(java.lang.String entryName)
                                    throws java.io.IOException

Opens an input stream for the specified entryName. The input stream will contain uncompressed data. The caller should close the returned input stream when it is done using it.

Throws:

java.io.IOException

exists

public boolean exists(java.lang.String entryName)

Checks for the existance of an entry with the given name.

Parameters:

entryName - the name of the entry

Returns:

true if the entry exists in this JAR file, false otherwise

isDirectory

public boolean isDirectory(java.lang.String entryName)

Determines whether an entry exists and is a direcory.

Parameters:

entryName - the name of the JAR entry

Returns:

true if the entry exists and is a directory, false otherwise

flushCache

public static void flushCache()

getBytes

public byte[] getBytes(java.lang.String entryName)
                throws java.io.IOException

Returns a byte array with the uncompressed data corresponding to entryName.

Throws:

java.io.IOException

getCompressedSize

public long getCompressedSize(java.lang.String entryName)

Returns the compressed size of a JAR entry.

Returns:

The compressed size of the entry, or -1 if the entry could not be found.

getTimestamp

public long getTimestamp(java.lang.String entryName)

Get the timestamp of a JAR entry.

Parameters:

entryName - the name of the JAR entry

Returns:

the timestamp of the entry

getTimestamp

public long getTimestamp()

Get the timestamp of the index. This is the timestamp of the JAR file at the time the index was last built.

Returns:

the timestamp of the index

runWhileClosed

public static void runWhileClosed(java.lang.Runnable r)

Run a task while the JAR indexes corresponding to user JARs are locked closed. The JAR files will be unlocked as soon as the task is finished.

Parameters:

r - the task to run