Package loci.common
Class S3Handle
- java.lang.Object
-
- loci.common.StreamHandle
-
- loci.common.S3Handle
-
- All Implemented Interfaces:
DataInput
,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
-
Nested classes/interfaces inherited from class loci.common.StreamHandle
StreamHandle.Settings
-
-
Field Summary
Fields Modifier and Type Field Description static 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 Pattern
SCHEME_PARSER
-
Constructor Summary
Constructors Constructor Description S3Handle(String url)
Open an S3 fileS3Handle(String uristr, boolean initialize, StreamHandle.Settings s)
Open an S3 file
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static String
cacheObject(String url, StreamHandle.Settings s)
Download an S3 object to a file system cache if it doesn't already existstatic boolean
canHandleScheme(String url)
Return true if this is a URL with an s3 schemeprotected void
connect()
Connect to the serverprotected void
downloadObject(Path destination)
boolean
exists()
Does this represent an accessible location?String
getBucket()
String
getCacheKey()
String
getPath()
int
getPort()
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.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 Detail
-
DEFAULT_S3_PROTOCOL
public static final String DEFAULT_S3_PROTOCOL
Default protocol for fetching s3://- See Also:
- Constant Field Values
-
SCHEME_PARSER
protected static final Pattern SCHEME_PARSER
-
S3_MAX_FORWARD_SEEK
protected static final int S3_MAX_FORWARD_SEEK
If seeking more than this distance reset and reopen at offset- See Also:
- Constant Field Values
-
-
Constructor Detail
-
S3Handle
public S3Handle(String url) throws IOException
Open an S3 file- Parameters:
url
- the full URL to the S3 resource- Throws:
IOException
- if there is an error during opening
-
S3Handle
public S3Handle(String uristr, boolean initialize, StreamHandle.Settings s) throws IOException
Open 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:
IOException
- if there is an error during opening
-
-
Method Detail
-
canHandleScheme
public static boolean canHandleScheme(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 IOException
Connect to the server- Throws:
IOException
- if there was an error connecting to the server
-
initialize
protected void initialize() throws IOException, S3ClientServiceException
Check bucket or object exists- Throws:
IOException
- if unable to get the objectS3ClientServiceException
- if unable to get the object
-
getServer
public String getServer()
-
getPort
public int getPort()
-
getBucket
public String getBucket()
-
getPath
public String getPath()
-
cacheObject
public static String cacheObject(String url, StreamHandle.Settings s) throws IOException, HandleException
Download 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:
IOException
- if there is an error during reading or writingHandleException
- if no destination for the cache is provided
-
getCacheKey
public String getCacheKey()
-
downloadObject
protected void downloadObject(Path destination) throws HandleException, IOException
- Throws:
HandleException
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 IOException
Description 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:
IOException
- if the length cannot be retrieved
-
seek
public void seek(long pos) throws IOException
Description 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:
IOException
- ifpos
is invalid or the seek fails- See Also:
StreamHandle.seek(long)
-
resetStream
protected void resetStream() throws IOException
Description 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:
IOException
- if the stream cannot be reset- See Also:
StreamHandle.resetStream()
-
exists
public boolean exists() throws IOException
Does this represent an accessible location?- Specified by:
exists
in interfaceIRandomAccess
- Overrides:
exists
in classStreamHandle
- Returns:
- true if this location is accessible
- Throws:
IOException
- if unable to determine whether this location is accessible
-
resetStream
protected void resetStream(long offset) throws IOException
Reset the stream to an offset position- Parameters:
offset
- Offset into object- Throws:
IOException
- if there is an error during reading or writing
-
-