Package loci.common
Class S3Handle
java.lang.Object
loci.common.StreamHandle
loci.common.S3Handle
- All Implemented Interfaces:
java.io.DataInput
,java.io.DataOutput
,IRandomAccess
public class S3Handle extends StreamHandle
Provides random access to S3 buckets using the IRandomAccess interface.
Instances of S3Handle are read-only.
- See Also:
IRandomAccess
,StreamHandle
,URLConnection
-
Nested Class Summary
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
DEFAULT_S3_PROTOCOL
Default protocol for fetching s3://protected static int
S3_MAX_FORWARD_SEEK
If seeking more than this distance reset and reopen at offsetprotected static java.util.regex.Pattern
SCHEME_PARSER
-
Constructor Summary
Constructors Constructor Description S3Handle(java.lang.String url)
Open an S3 fileS3Handle(java.lang.String uristr, boolean initialize, StreamHandle.Settings s)
Open an S3 file -
Method Summary
Modifier and Type Method Description static java.lang.String
cacheObject(java.lang.String url, StreamHandle.Settings s)
Download an S3 object to a file system cache if it doesn't already existstatic boolean
canHandleScheme(java.lang.String url)
Return true if this is a URL with an s3 schemeprotected void
connect()
Connect to the serverprotected void
downloadObject(java.nio.file.Path destination)
boolean
exists()
Does this represent an accessible location?java.lang.String
getBucket()
java.lang.String
getCacheKey()
java.lang.String
getPath()
int
getPort()
java.lang.String
getServer()
protected void
initialize()
Check bucket or object existsboolean
isBucket()
Is this an accessible bucket? TODO: If this bucket doesn't exist do we return false or thrown an exception?long
length()
Returns the length of this stream.protected void
resetStream()
Close and reopen the stream; the stream pointer and mark should be reset to 0.protected void
resetStream(long offset)
Reset the stream to an offset positionvoid
seek(long pos)
Sets the stream pointer offset, measured from the beginning of this stream, at which the next read or write occurs.java.lang.String
toString()
Methods inherited from class loci.common.StreamHandle
close, getFilePointer, getOrder, read, read, read, read, readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, setOrder, skipBytes, skipBytes, write, write, write, write, write, writeBoolean, writeByte, writeBytes, writeChar, writeChars, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF
-
Field Details
-
DEFAULT_S3_PROTOCOL
public static final java.lang.String DEFAULT_S3_PROTOCOLDefault protocol for fetching s3://- See Also:
- Constant Field Values
-
SCHEME_PARSER
protected static final java.util.regex.Pattern SCHEME_PARSER -
S3_MAX_FORWARD_SEEK
protected static final int S3_MAX_FORWARD_SEEKIf seeking more than this distance reset and reopen at offset- See Also:
- Constant Field Values
-
-
Constructor Details
-
S3Handle
public S3Handle(java.lang.String url) throws java.io.IOExceptionOpen an S3 file- Parameters:
url
- the full URL to the S3 resource- Throws:
java.io.IOException
- if there is an error during opening
-
S3Handle
public S3Handle(java.lang.String uristr, boolean initialize, StreamHandle.Settings s) throws java.io.IOExceptionOpen an S3 file- Parameters:
uristr
- the full URL to the S3 resourceinitialize
- If true open the stream, otherwise just parse connection strings
- custom settings object- Throws:
java.io.IOException
- if there is an error during opening
-
-
Method Details
-
canHandleScheme
public static boolean canHandleScheme(java.lang.String url)Return true if this is a URL with an s3 scheme- Parameters:
url
- URL- Returns:
- true if this class can handle url
-
connect
protected void connect() throws java.io.IOExceptionConnect to the server- Throws:
java.io.IOException
- if there was an error connecting to the server
-
initialize
Check bucket or object exists- Throws:
java.io.IOException
- if unable to get the objectS3ClientServiceException
- if unable to get the object
-
getServer
public java.lang.String getServer() -
getPort
public int getPort() -
getBucket
public java.lang.String getBucket() -
getPath
public java.lang.String getPath() -
cacheObject
public static java.lang.String cacheObject(java.lang.String url, StreamHandle.Settings s) throws java.io.IOException, HandleExceptionDownload an S3 object to a file system cache if it doesn't already exist- Parameters:
url
- the full URL to the S3 resources
- custom settings object- Returns:
- File path to the cached object
- Throws:
java.io.IOException
- if there is an error during reading or writingHandleException
- if no destination for the cache is provided
-
getCacheKey
public java.lang.String getCacheKey() -
downloadObject
protected void downloadObject(java.nio.file.Path destination) throws HandleException, java.io.IOException- Throws:
HandleException
java.io.IOException
-
isBucket
public boolean isBucket()Is this an accessible bucket? TODO: If this bucket doesn't exist do we return false or thrown an exception?- Returns:
- True if a bucket
-
length
public long length() throws java.io.IOExceptionDescription copied from interface:IRandomAccess
Returns the length of this stream.- Specified by:
length
in interfaceIRandomAccess
- Overrides:
length
in classStreamHandle
- Returns:
- the length in bytes of the stream
- Throws:
java.io.IOException
- if the length cannot be retrieved
-
seek
public void seek(long pos) throws java.io.IOExceptionDescription copied from interface:IRandomAccess
Sets the stream pointer offset, measured from the beginning of this stream, at which the next read or write occurs.- Specified by:
seek
in interfaceIRandomAccess
- Overrides:
seek
in classStreamHandle
- Parameters:
pos
- new byte offset (pointer) in the current stream. Unless otherwise noted, may be larger or smaller than the current pointer, but must be non-negative and less than the value of #length()- Throws:
java.io.IOException
- ifpos
is invalid or the seek fails- See Also:
StreamHandle.seek(long)
-
resetStream
protected void resetStream() throws java.io.IOExceptionDescription copied from class:StreamHandle
Close and reopen the stream; the stream pointer and mark should be reset to 0. This method is called if we need to seek backwards within the stream.- Specified by:
resetStream
in classStreamHandle
- Throws:
java.io.IOException
- if the stream cannot be reset- See Also:
StreamHandle.resetStream()
-
exists
public boolean exists() throws java.io.IOExceptionDoes this represent an accessible location?- Specified by:
exists
in interfaceIRandomAccess
- Overrides:
exists
in classStreamHandle
- Returns:
- true if this location is accessible
- Throws:
java.io.IOException
- if unable to determine whether this location is accessible
-
resetStream
protected void resetStream(long offset) throws java.io.IOExceptionReset the stream to an offset position- Parameters:
offset
- Offset into object- Throws:
java.io.IOException
- if there is an error during reading or writing
-
toString
public java.lang.String toString()- Overrides:
toString
in classjava.lang.Object
-