Package org.geotools.data.shapefile.files

Class ShpFiles

Object

ShpFiles

public class ShpFiles
extends Object

The collection of all the files that are the shapefile and its metadata and indices.

This class has methods for performing actions on the files. Currently mainly for obtaining read and write channels and streams. But in the future a move method may be introduced.

Note: The method that require locks (such as getInputStream()) will automatically acquire locks and the javadocs should document how to release the lock. Therefore the methods acquireRead(ShpFileType, FileReader) and acquireWrite(ShpFileType, FileWriter) svn

Author:

jesse

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ShpFiles.State

Field Summary

Fields

Modifier and Type	Field	Description
static boolean	DEFAULT_SKIP_SCAN

Constructor Summary

Constructors

Constructor	Description
ShpFiles(File file)	Searches for all the files and adds then to the map of files.
ShpFiles(File file, boolean skipScan)
ShpFiles(String fileName)
ShpFiles(String fileName, boolean skipScan)	Searches for all the files and adds then to the map of files.
ShpFiles(URL url)	Searches for all the files and adds then to the map of files.
ShpFiles(URL url, boolean skipScan)	Searches for all the files and adds then to the map of files.

Method Summary

Modifier and Type	Method	Description
URL	acquireRead(ShpFileType type, FileReader requestor)	Acquire a URL for read only purposes.
File	acquireReadFile(ShpFileType type, FileReader requestor)	Acquire a File for read only purposes.
URL	acquireWrite(ShpFileType type, FileWriter requestor)	Acquire a URL for read and write purposes.
File	acquireWriteFile(ShpFileType type, FileWriter requestor)	Acquire a File for read and write purposes.
boolean	delete()	Delete all the shapefile files.
void	dispose()
boolean	exists(ShpFileType fileType)	Returns true if the file exists.
protected void	finalize()	This verifies that this class has been closed correctly (nothing locking)
String	get(ShpFileType type)	Returns the string form of the url that identifies the file indicated by the type parameter or null if it is known that the file does not exist.
Map<ShpFileType,String>	getFileNames()	Returns the URLs (in string form) of all the files for the shapefile datastore.
InputStream	getInputStream(ShpFileType type, FileReader requestor)	Opens a input stream for the indicated file.
OutputStream	getOutputStream(ShpFileType type, FileWriter requestor)	Opens a output stream for the indicated file.
ReadableByteChannel	getReadChannel(ShpFileType type, FileReader requestor)	Obtain a ReadableByteChannel from the given URL.
StorageFile	getStorageFile(ShpFileType type)	Obtains a Storage file for the type indicated.
String	getTypeName()
WritableByteChannel	getWriteChannel(ShpFileType type, FileWriter requestor)	Obtain a WritableByteChannel from the given URL.
boolean	isGz()
boolean	isLocal()	Determine if the location of this shapefile is local or remote.
boolean	isMemoryMapCacheEnabled()	Returns the status of the memory map cache.
boolean	isWritable()	Returns true if the files are writable
void	logCurrentLockers(Level logLevel)	Writes to the log all the lockers and when they were constructed.
int	numberOfLocks()	Returns the number of locks on the current set of shapefile files.
void	setMemoryMapCacheEnabled(boolean memoryMapCacheEnabled)	Enables the memory map cache.
Result<URL,ShpFiles.State>	tryAcquireRead(ShpFileType type, FileReader requestor)	Tries to acquire a URL for read only purposes.
Result<URL,ShpFiles.State>	tryAcquireWrite(ShpFileType type, FileWriter requestor)	Tries to acquire a URL for read/write purposes.
void	unlockRead(File file, FileReader requestor)	Unlocks a read lock.
void	unlockRead(URL url, FileReader requestor)	Unlocks a read lock.
void	unlockWrite(File file, FileWriter requestor)	Unlocks a write lock.
void	unlockWrite(URL url, FileWriter requestor)	Unlocks a write lock.

Methods inherited from class Object

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

Field Detail

DEFAULT_SKIP_SCAN

public static final boolean DEFAULT_SKIP_SCAN

See Also:

Constant Field Values

Constructor Detail

ShpFiles

public ShpFiles(String fileName)
         throws MalformedURLException

Throws:

MalformedURLException

ShpFiles

public ShpFiles(String fileName,
                boolean skipScan)
         throws MalformedURLException

Searches for all the files and adds then to the map of files.

Parameters:

fileName - the filename or url of any one of the shapefile files

skipScan - skip the scan for alternative shapefile extensions (i.e. .SHP, .shp.XML, ...)

Throws:

MalformedURLException - if it isn't possible to create a URL from string. It will be used to create a file and create a URL from that if both fail this exception is thrown

ShpFiles

public ShpFiles(File file)
         throws MalformedURLException

Searches for all the files and adds then to the map of files.

Parameters:

file - any one of the shapefile files

Throws:

FileNotFoundException - if the shapefile associated with file is not found

MalformedURLException

ShpFiles

public ShpFiles(File file,
                boolean skipScan)
         throws MalformedURLException

Throws:

MalformedURLException

ShpFiles

public ShpFiles(URL url)
         throws IllegalArgumentException

Searches for all the files and adds then to the map of files.

Parameters:

url - any one of the shapefile files

Throws:

IllegalArgumentException

ShpFiles

public ShpFiles(URL url,
                boolean skipScan)
         throws IllegalArgumentException

Searches for all the files and adds then to the map of files.

Parameters:

url - any one of the shapefile files

skipScan - avoid searching for other extensions when missing.

Throws:

IllegalArgumentException

Method Detail

finalize

protected void finalize()
                 throws Throwable

This verifies that this class has been closed correctly (nothing locking)

Overrides:

finalize in class Object

Throws:

Throwable

dispose

public void dispose()

logCurrentLockers

public void logCurrentLockers(Level logLevel)

Writes to the log all the lockers and when they were constructed.

Parameters:

logLevel - the level at which to log.

getFileNames

public Map<ShpFileType,String> getFileNames()

Returns the URLs (in string form) of all the files for the shapefile datastore.

Returns:

the URLs (in string form) of all the files for the shapefile datastore.

get

public String get(ShpFileType type)

Returns the string form of the url that identifies the file indicated by the type parameter or null if it is known that the file does not exist.

Note: a URL should NOT be constructed from the string instead the URL should be obtained through calling one of the aquireLock methods.

Parameters:

type - indicates the type of file the caller is interested in.

Returns:

the string form of the url that identifies the file indicated by the type parameter or null if it is known that the file does not exist.

numberOfLocks

public int numberOfLocks()

Returns the number of locks on the current set of shapefile files. This is not thread safe so do not count on it to have a completely accurate picture but it can be useful debugging

Returns:

the number of locks on the current set of shapefile files.

acquireReadFile

public File acquireReadFile(ShpFileType type,
                            FileReader requestor)

Acquire a File for read only purposes. It is recommended that get*Stream or get*Channel methods are used when reading or writing to the file is desired.

Parameters:

type - the type of the file desired.

requestor - the object that is requesting the File. The same object must release the lock and is also used for debugging.

Returns:

the File type requested

See Also:

getInputStream(ShpFileType, FileReader), getReadChannel(ShpFileType, FileReader), #getWriteChannel(ShpFileType, FileReader)

acquireRead

public URL acquireRead(ShpFileType type,
                       FileReader requestor)

Acquire a URL for read only purposes. It is recommended that get*Stream or get*Channel methods are used when reading or writing to the file is desired.

Parameters:

type - the type of the file desired.

requestor - the object that is requesting the URL. The same object must release the lock and is also used for debugging.

Returns:

the URL to the file of the type requested

See Also:

getInputStream(ShpFileType, FileReader), getReadChannel(ShpFileType, FileReader), #getWriteChannel(ShpFileType, FileReader)

tryAcquireRead

public Result<URL,ShpFiles.State> tryAcquireRead(ShpFileType type,
                                                       FileReader requestor)

Tries to acquire a URL for read only purposes. Returns null if the acquire failed or if the file does not.

It is recommended that get*Stream or get*Channel methods are used when reading or writing to the file is desired.

Parameters:

type - the type of the file desired.

requestor - the object that is requesting the URL. The same object must release the lock and is also used for debugging.

Returns:

A result object containing the URL or the reason for the failure.

See Also:

getInputStream(ShpFileType, FileReader), getReadChannel(ShpFileType, FileReader), #getWriteChannel(ShpFileType, FileReader)

unlockRead

public void unlockRead(File file,
                       FileReader requestor)

Unlocks a read lock. The file and requestor must be the the same as the one of the lockers.

Parameters:

file - file that was locked

requestor - the class that requested the file

unlockRead

public void unlockRead(URL url,
                       FileReader requestor)

Unlocks a read lock. The url and requestor must be the the same as the one of the lockers.

Parameters:

url - url that was locked

requestor - the class that requested the url

acquireWriteFile

public File acquireWriteFile(ShpFileType type,
                             FileWriter requestor)

Acquire a File for read and write purposes.

It is recommended that get*Stream or get*Channel methods are used when reading or writing to the file is desired.

Parameters:

type - the type of the file desired.

requestor - the object that is requesting the File. The same object must release the lock and is also used for debugging.

Returns:

the File to the file of the type requested

See Also:

getInputStream(ShpFileType, FileReader), getReadChannel(ShpFileType, FileReader), #getWriteChannel(ShpFileType, FileReader)

acquireWrite

public URL acquireWrite(ShpFileType type,
                        FileWriter requestor)

Acquire a URL for read and write purposes.

It is recommended that get*Stream or get*Channel methods are used when reading or writing to the file is desired.

Parameters:

type - the type of the file desired.

requestor - the object that is requesting the URL. The same object must release the lock and is also used for debugging.

Returns:

the URL to the file of the type requested

See Also:

getInputStream(ShpFileType, FileReader), getReadChannel(ShpFileType, FileReader), #getWriteChannel(ShpFileType, FileReader)

tryAcquireWrite

public Result<URL,ShpFiles.State> tryAcquireWrite(ShpFileType type,
                                                        FileWriter requestor)

Tries to acquire a URL for read/write purposes. Returns null if the acquire failed or if the file does not exist

It is recommended that get*Stream or get*Channel methods are used when reading or writing to the file is desired.

Parameters:

type - the type of the file desired.

requestor - the object that is requesting the URL. The same object must release the lock and is also used for debugging.

Returns:

A result object containing the URL or the reason for the failure.

See Also:

getInputStream(ShpFileType, FileReader), getReadChannel(ShpFileType, FileReader), #getWriteChannel(ShpFileType, FileReader)

unlockWrite

public void unlockWrite(File file,
                        FileWriter requestor)

Unlocks a write lock. The file and requestor must be the the same as the one of the lockers.

Parameters:

file - file that was locked

requestor - the class that requested the file

unlockWrite

public void unlockWrite(URL url,
                        FileWriter requestor)

Unlocks a write lock. The requestor must be have previously obtained a lock for the url.

Parameters:

url - url that was locked

requestor - the class that requested the url

isLocal

public boolean isLocal()

Determine if the location of this shapefile is local or remote.

Returns:

true if local, false if remote

isGz

public boolean isGz()

Returns:

whether the files are gzip-ped.

isWritable

public boolean isWritable()

Returns true if the files are writable

delete

public boolean delete()

Delete all the shapefile files. If the files are not local or the one files cannot be deleted return false.

getInputStream

public InputStream getInputStream(ShpFileType type,
                                  FileReader requestor)
                           throws IOException

Opens a input stream for the indicated file. A read lock is requested at the method call and released on close.

Parameters:

type - the type of file to open the stream to.

requestor - the object requesting the stream

Returns:

an input stream

Throws:

IOException - if a problem occurred opening the stream.

getOutputStream

public OutputStream getOutputStream(ShpFileType type,
                                    FileWriter requestor)
                             throws IOException

Opens a output stream for the indicated file. A write lock is requested at the method call and released on close.

Parameters:

type - the type of file to open the stream to.

requestor - the object requesting the stream

Returns:

an output stream

Throws:

IOException - if a problem occurred opening the stream.

getReadChannel

public ReadableByteChannel getReadChannel(ShpFileType type,
                                          FileReader requestor)
                                   throws IOException

Obtain a ReadableByteChannel from the given URL. If the url protocol is file, a FileChannel will be returned. Otherwise a generic channel will be obtained from the urls input stream.

A read lock is obtained when this method is called and released when the channel is closed.

Parameters:

type - the type of file to open the channel to.

requestor - the object requesting the channel

Throws:

IOException

getWriteChannel

public WritableByteChannel getWriteChannel(ShpFileType type,
                                           FileWriter requestor)
                                    throws IOException

Obtain a WritableByteChannel from the given URL. If the url protocol is file, a FileChannel will be returned. Currently, this method will return a generic channel for remote urls, however both shape and dbf writing can only occur with a local FileChannel channel.

A write lock is obtained when this method is called and released when the channel is closed.

Parameters:

type - the type of file to open the stream to.

requestor - the object requesting the stream

Returns:

a WritableByteChannel for the provided file type

Throws:

IOException - if there is an error opening the stream

getStorageFile

public StorageFile getStorageFile(ShpFileType type)
                           throws IOException

Obtains a Storage file for the type indicated. An id is provided so that the same file can be obtained at a later time with just the id

Parameters:

type - the type of file to create and return

Returns:

StorageFile

Throws:

IOException - if temporary files cannot be created

getTypeName

public String getTypeName()

isMemoryMapCacheEnabled

public boolean isMemoryMapCacheEnabled()

Returns the status of the memory map cache. When enabled the memory mapped portions of the files are cached and shared (giving each thread a clone of it)

setMemoryMapCacheEnabled

public void setMemoryMapCacheEnabled(boolean memoryMapCacheEnabled)

Enables the memory map cache. When enabled the memory mapped portions of the files are cached and shared (giving each thread a clone of it)

exists

public boolean exists(ShpFileType fileType)
               throws IllegalArgumentException

Returns true if the file exists. Throws an exception if the file is not local.

Parameters:

fileType - the type of file to check existance for.

Returns:

true if the file exists.

Throws:

IllegalArgumentException - if the files are not local.