public final class JarIndex
extends java.lang.Object
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.
Modifier and Type | Class and Description |
---|---|
static interface |
JarIndex.Visitor
Visits entries in this index.
|
Modifier and Type | Method and Description |
---|---|
static void |
clearCache()
Clears the cache that holds on to JarIndices of URL's as long as those
JarIndices are in use.
|
static void |
closeUserJars()
Deprecated.
All file handle caching has been removed
|
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.
|
boolean |
existsEx(java.lang.String entryName)
Checks for the existance of an entry with the given name.
|
static void |
flushCache()
Deprecated.
All file handle caching has been removed
|
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.
|
long |
getCompressedSizeEx(java.lang.String entryName)
Returns the compressed size of a JAR entry.
|
java.lang.String[] |
getEntries()
Fetch a list of all entry names.
|
java.lang.String[] |
getEntriesEx()
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. |
static JarIndex |
getInstance(java.net.URL jarFileURL,
boolean forceJarTimestampCheck)
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 |
getSizeEx(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.
|
long |
getTimestampEx(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 |
isDirectoryEx(java.lang.String entryName)
Determines whether an entry exists and is a direcory.
|
boolean |
isEmpty()
Determines whether this JAR index is currently empty.
|
boolean |
isEmptyEx()
Determines whether this JAR index is currently empty.
|
static void |
leaveJarsOpen()
Deprecated.
All file handle caching has been removed
|
java.lang.String[] |
list(java.lang.String dirEntryName)
List the entries of a directory.
|
java.lang.String[] |
listEx(java.lang.String dirEntryName)
List the entries of a directory.
|
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 JarIndex 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.
|
public static JarIndex getInstance(java.net.URL jarFileURL)
JarIndex
instance. The JAR timestamp will be checked to
make sure any cached instance is still valid. This method is a good
choice if it's vital that the latest JarIndex is retrieved, but it
does have a time penalty; otherwise use getInstance(URL, boolean)
which allows for smart timestamp checking which in almost all cases
returns the latest JarIndex.jarFileURL
- the URL of the JAR filegetInstance(URL, boolean)
public static JarIndex getInstance(java.net.URL jarFileURL, boolean forceJarTimestampCheck)
JarIndex
instance. If it's vital that the latest JarIndex
is retrieved, it's better to force a JAR timestamp check to determine if
any cached instance is still valid, but it does have a time penalty;
otherwise, let the smart caching code decide if any cached instance is
still valid, which in almost all cases returns the latest JarIndex.jarFileURL
- the URL of the JAR fileforceJarTimestampCheck
- if true, force a JAR timestamp checkgetInstance(URL)
public static void uncache(java.net.URL jarFileURL)
jarFileURL
- the URL of the JAR Filepublic boolean lockJarFile()
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.public void unlockJarFile()
public void visit(JarIndex.Visitor visitor) throws java.io.IOException
visitor
- the visitorjava.io.IOException
- if the JAR cannot be readpublic boolean isEmpty()
true
if the JAR index is empty or if an Exception
was thrown, false
otherwiseisEmptyEx()
public boolean isEmptyEx() throws java.io.IOException
true
if the JAR index is empty, false
otherwisejava.io.IOException
- when the jar file reader encounters an error while
reading the jar. The IOException might have another exception,
such as a ZipError, as the cause.@Deprecated public int dirEntryIndex(java.lang.String entryName)
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.@Deprecated public int entryIndex(java.lang.String entryName)
visit(Visitor)
to iterate the index entries.
The index returned by this method may become invalid if the JAR file
changes on disk.@Deprecated public static void closeUserJars()
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.
leaveJarsOpen()
,
runWhileClosed(Runnable)
@Deprecated public static void leaveJarsOpen()
closeUserJars()
was called.
It is strongly recommended that runWhileClosed(Runnable)
be used instead
of this method.leaveJarsOpen()
,
runWhileClosed(Runnable)
@Deprecated public int getNumEntries()
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.@Deprecated public JarIndexEntry getEntryAt(int i)
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.IndexOutOfBoundsException
- if the specified index is
less than 0 or greater than or equal to the number of indexed
entries.@Deprecated public java.lang.String getEntryNameAt(int i)
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.IndexOutOfBoundsException
- if the specified index is
less than 0 or greater than or equal to the number of indexed
entries.public java.lang.String[] getEntries()
getEntriesEx()
public java.lang.String[] getEntriesEx() throws java.io.IOException
java.io.IOException
- when the jar file reader encounters an error while
reading the jar. The IOException might have another exception,
such as a ZipError, as the cause.public long getSize(java.lang.String entryName)
entryName
- the name of the JAR entrygetSizeEx(String)
public long getSizeEx(java.lang.String entryName) throws java.io.IOException
entryName
- the name of the JAR entryjava.io.IOException
- when the jar file reader encounters an error while
reading the jar. The IOException might have another exception,
such as a ZipError, as the cause.public java.lang.String[] list(java.lang.String dirEntryName)
dirEntryName
- The name of the JAR directory entrylistEx(String)
public java.lang.String[] listEx(java.lang.String dirEntryName) throws java.io.IOException
dirEntryName
- The name of the JAR directory entryjava.io.IOException
- when the jar file reader encounters an error while
reading the jar. The IOException might have another exception,
such as a ZipError, as the cause.public java.io.InputStream openInputStream(java.lang.String entryName) throws java.io.IOException
entryName
.
The input stream will contain uncompressed data. The caller should close
the returned input stream when it is done using it.entryName
- the name of the JAR entryjava.io.IOException
- when the jar file reader encounters an error while
reading the jar. The IOException might have another exception,
such as a ZipError, as the cause.public boolean exists(java.lang.String entryName)
entryName
- the name of the JAR entrytrue
if the entry exists in this JAR file,
false
otherwise including after thrown ExceptionsexistsEx(String)
public boolean existsEx(java.lang.String entryName) throws java.io.IOException
entryName
- the name of the JAR entrytrue
if the entry exists in this JAR file,
false
otherwisejava.io.IOException
- when the jar file reader encounters an error while
reading the jar. The IOException might have another exception,
such as a ZipError, as the cause.public boolean isDirectory(java.lang.String entryName)
entryName
- the name of the JAR entrytrue
if the entry exists and is a directory,
false
otherwise including after thrown ExceptionsisDirectoryEx(String)
public boolean isDirectoryEx(java.lang.String entryName) throws java.io.IOException
entryName
- the name of the JAR entrytrue
if the entry exists and is a directory,
false
otherwisejava.io.IOException
- when the jar file reader encounters an error while
reading the jar. The IOException might have another exception,
such as a ZipError, as the cause.@Deprecated public static void flushCache()
public byte[] getBytes(java.lang.String entryName) throws java.io.IOException
entryName
.entryName
- the name of the JAR entryjava.io.IOException
- when the jar file reader encounters an error while
reading the jar. The IOException might have another exception,
such as a ZipError, as the cause.public long getCompressedSize(java.lang.String entryName)
entryName
- the name of the JAR entrygetCompressedSizeEx(String)
public long getCompressedSizeEx(java.lang.String entryName) throws java.io.IOException
entryName
- the name of the JAR entryjava.io.IOException
- when the jar file reader encounters an error while
reading the jar. The IOException might have another exception,
such as a ZipError, as the cause.public long getTimestamp(java.lang.String entryName)
entryName
- the name of the JAR entrygetTimestampEx(String)
public long getTimestampEx(java.lang.String entryName) throws java.io.IOException
entryName
- the name of the JAR entryjava.io.IOException
- when the jar file reader encounters an error while
reading the jar. The IOException might have another exception,
such as a ZipError, as the cause.public long getTimestamp()
public static void clearCache()
public static void runWhileClosed(java.lang.Runnable r)
r
- the task to run