java.lang.Object

io.odilon.client.ODClient

All Implemented Interfaces:: OdilonClient

public class ODClient extends Object implements OdilonClient

This class implements the Interface OdilonClient, Odilon Object Storage client.

For examples on using this library, please visit http://odilon.io

Author:: atolomei@novamens.com (Alejandro Tolomei), aferraria@novamens.com (Alejo Ferraria)

Field Summary

Fields

Modifier and Type

Field

Description

static final int

DEFAULT_CONNECTION_TIMEOUT

default network I/O timeout is 15 minutes

static final String

DEFAULT_USER_AGENT
Constructor Summary

Constructors

Constructor

Description

ODClient(String endpoint, int port, String accessKey, String secretKey)

By default the server has the following settings in file odilon.properties

ODClient(String endpoint, int port, String accessKey, String secretKey, boolean secure)

ODClient(String endpoint, int port, String accessKey, String secretKey, boolean isSecure, boolean acceptAllCertificates)
Method Summary

Modifier and Type

Method

Description

void

addServiceRequest(String requestClass)

void

close()

Shutdown Isn't Necessary because the threads and connections that are held will be released automatically if they remain idle

void

createBucket(String bucketName)

Creates a new Bucket.

OffsetDateTime

created()

void

deleteAllBucketVersions(String bucketName)

Deletes all the previous versions of all the Objects in the Bucket.
Note that it does not delete the current version of the objects (called head version).

void

deleteBucket(String bucketName)

Deletes a Bucket.

void

deleteObject(String bucketName, String objectName)

Removes an object from a bucket.

void

deleteObjectAllVersions(String bucketName, String objectName)

Deletes all the Object's previous versions, it does not delete the object current version (head version).

boolean

existsBucket(String bucketName)

Returns true if a bucket with name bucketName exists

boolean

existsObject(String bucketName, String objectName)

Checks for the existence of an Object.

io.odilon.model.Bucket

getBucket(String bucketName)

Returns the Bucket

String

getCharset()

int

getChunkSize()

InputStream

getObject(String bucketName, String objectName)

Gets entire object's data as InputStream in given bucket.

void

getObject(String bucketName, String objectName, String fileName)

Gets object's data and stores it to given file name.

protected com.fasterxml.jackson.databind.ObjectMapper

getObjectMapper()

io.odilon.model.ObjectMetadata

getObjectMetadata(String bucketName, String objectName)

Returns ObjectMetadata of given object in given bucket.

io.odilon.model.ObjectMetadata

getObjectMetadataPreviousVersion(String bucketName, String objectName)

Returns ObjectMetadata of previous version

List<io.odilon.model.ObjectMetadata>

getObjectMetadataPreviousVersionAll(String bucketName, String objectName)

Returns all previous versions of an Object, sorted by version number

InputStream

getObjectPreviousVersion(String bucketName, String objectName)

Returns the binary data of the object's previous version or null if there is no previous version.

InputStream

getObjectVersion(String bucketName, String objectName, int version)

get InputStream of the version passed as parameter, null if head is version 0 parameter is non existent or previous versions were wiped

String

getPresignedObjectUrl(String bucketName, String objectName)

Returns an presigned URL to download the binary object with default expiry time.

String

getPresignedObjectUrl(String bucketName, String objectName, Optional<Integer> expires)

A presigned URL is a way to grant temporary access to an Object, for example in an HTML webpage.

String

getPresignedObjectUrl(String bucketName, String objectName, Optional<Integer> expires, Map<String,String> reqParams)

A presigned URL is a way to grant temporary access to an Object, for example in an HTML webpage.

String

getUrl()

Returns the url of the Odilon server

boolean

hasVersions(String bucketName, String objectName)

Returns true if the Object has previous versions, ie.

void

ignoreCertCheck()

Ignores check on server certificate for HTTPS connection.

boolean

isAcceptAllCertificates()

boolean

isEmpty(String bucketName)

Returns true if the bucket has no Objects, otherwise false

boolean

isHTTPS()

boolean

isSSL()

boolean

isValidBucketName(String name)

Returns true if the String bucketName is a valid name for an Odilon Bucket

boolean

isValidObjectName(String objectName)

Returns true if the String objectName is a valid name for an Odilon object

boolean

isVersionControl()

Checks if the server has version control enabled

List<io.odilon.model.Bucket>

listBuckets()

Returns all buckets, sorted alphabetically

io.odilon.model.list.ResultSet<io.odilon.model.list.Item<io.odilon.model.ObjectMetadata>>

listObjects(io.odilon.model.Bucket bucket)

Lists the objects in the Bucket.

io.odilon.model.list.ResultSet<io.odilon.model.list.Item<io.odilon.model.ObjectMetadata>>

listObjects(String bucketName)

Item is a wrapper for Lists and other Iterable structures of T where some elements may not be a T but an error.
T must be Serializable

io.odilon.model.list.ResultSet<io.odilon.model.list.Item<io.odilon.model.ObjectMetadata>>

listObjects(String bucketName, String prefix)

Lists the objects in the Bucket.

io.odilon.model.list.ResultSet<io.odilon.model.list.Item<io.odilon.model.ObjectMetadata>>

listObjects(String bucketName, Optional<String> prefix, Optional<Integer> pageSize)

Lists the objects in the Bucket.

io.odilon.model.MetricsValues

metrics()

Returns an instance of MetricsValues with info related to the activity of the server

String

ping()

Returns the String "ok" or a String with the error reported by the Server.

io.odilon.model.ObjectMetadata

putObject(String bucketName, String objectName, File file)

Uploads the File file to the server

io.odilon.model.ObjectMetadata

putObject(String bucketName, String objectName, Optional<List<String>> customTags, File file)

Uploads a File or any other binary stream to the server.

io.odilon.model.ObjectMetadata

putObjectStream(String bucketName, String objectName, InputStream stream, String fileName)

Uploads a File or any other binary stream to the server.

io.odilon.model.ObjectMetadata

putObjectStream(String bucketName, String objectName, InputStream stream, String fileName, String contentType)

Uploads a File or any other binary stream to the server.

io.odilon.model.ObjectMetadata

putObjectStream(String bucketName, String objectName, InputStream stream, Optional<String> fileName, Optional<Long> size)

Uploads a File or any other binary stream to the server.

io.odilon.model.ObjectMetadata

putObjectStream(String bucketName, String objectName, InputStream stream, Optional<String> fileName, Optional<Long> size, Optional<String> contentType)

Uploads a InputStream to the server.

io.odilon.model.ObjectMetadata

putObjectStream(String bucketName, String objectName, InputStream stream, Optional<String> fileName, Optional<Long> size, Optional<String> contentType, Optional<List<String>> customTags)

Uploads a File or any other binary stream to the server.

void

renameBucket(String bucketName, String newBucketName)

Renames a Bucket.

void

restoreObjectPreviousVersions(String bucketName, String objectName)

Restores the previous version of the Object and deletes current version.

void

setCharset(String c)

void

setChunkSize(int chunkSize)

void

setPresignedUrl(String presignedEndPoint)

Sets a specific url for presigned urls.

void

setPresignedUrl(String presignedEndPoint, boolean presignedSSL)

void

setPresignedUrl(String presignedEndPoint, int port, boolean presignedSSL)

void

setTimeout(long connectTimeoutMilliseconds, long writeTimeoutMilliseconds, long readTimeoutMilliseconds)

Sets HTTP connect, write and read timeouts.

io.odilon.model.SystemInfo

systemInfo()

Returns SystemInfo

String

toJSON()

String

toString()

void

traceOff()

Disables HTTP call tracing previously enabled.

void

traceOn(OutputStream traceStream)

enabled printing the request-response raw info to a stream

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details
- DEFAULT_CONNECTION_TIMEOUT
  
  public static final int DEFAULT_CONNECTION_TIMEOUT
  
  default network I/O timeout is 15 minutes
  See Also:
  
  Constant Field Values
- DEFAULT_USER_AGENT
  
  public static final String DEFAULT_USER_AGENT
Constructor Details
- ODClient
  
  public ODClient(String endpoint, int port, String accessKey, String secretKey)
  By default the server has the following settings in file odilon.properties
  
  Note that these parameters can not be defined or modified by the client. They are configured on the server's odilon.properties file
  
  port. 9234
  
  accessKey. "odilon"
  
  secretKey. "odilon"
  Parameters:
  
  endpoint - can not be null
  
  port - can not be null (normally default port is 9234)
  
  accessKey - can not be null (default is "odilon")
  
  secretKey - can not be null (default is "odilon")
- ODClient
  
  public ODClient(String endpoint, int port, String accessKey, String secretKey, boolean secure)
- ODClient
  
  public ODClient(String endpoint, int port, String accessKey, String secretKey, boolean isSecure, boolean acceptAllCertificates)
  
  Parameters:
  
  endpoint - can not be null
  
  port - can not be null (normally default port is 9234)
  
  accessKey - can not be null
  
  secretKey - can not be null
  
  isSecure - whether to use SSL
  
  acceptAllCertificates - for self signed certificates
Method Details
- setPresignedUrl
  
  public void setPresignedUrl(String presignedEndPoint)
  
  Description copied from interface: OdilonClient
  Sets a specific url for presigned urls.
  
  A presigned URL is a way to grant temporary access to an Object, for example in an HTML webpage. It remains valid for a limited period of time which is specified when the URL is generated.
  
  Sometimes it may be useful for the presigned url to have a different prefix than the endpoint used to interact with the server.
  For example: The server may be accessible by an application server at
  http://localhost:9234
  and the presigned url generated to be distributed in a html web page be reachable at:
  http://files.odilon.io
  
  ODilonClient client = new ODClient(("http://localhost", 9234, "odilon", "odilon"); // The firewall blocks port 9234 and the webserver is configured to allow access to // the odilon server at http://files.myportal.com client.setPresignedUrl("files.myportal.com", 80, false);
  Specified by:
  
  setPresignedUrl in interface OdilonClient
- setPresignedUrl
  
  public void setPresignedUrl(String presignedEndPoint, boolean presignedSSL)
  
  Specified by:
  
  setPresignedUrl in interface OdilonClient
- setPresignedUrl
  
  public void setPresignedUrl(String presignedEndPoint, int port, boolean presignedSSL)
  
  Specified by:
  
  setPresignedUrl in interface OdilonClient
- putObjectStream
  
  public io.odilon.model.ObjectMetadata putObjectStream(String bucketName, String objectName, InputStream stream, String fileName) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Uploads a File or any other binary stream to the server. It will create a new object or update an existing one.
  
  This method calls OdilonClient.putObject(java.lang.String, java.lang.String, java.io.File)
  
  Specified by:
  
  putObjectStream in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  stream - InputStream with the binary data to upload
  
  fileName - name of the File uploaded
  
  Returns:
  
  the ObjectMetadata of the Object Throws ODClientException See Minio to Odilon migration sample program on GitHub
  
  Throws:
  
  ODClientException
- putObjectStream
  
  public io.odilon.model.ObjectMetadata putObjectStream(String bucketName, String objectName, InputStream stream, Optional<String> fileName, Optional<Long> size) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Uploads a File or any other binary stream to the server. It will create a new object or update an existing one.
  
  This method calls OdilonClient.putObject(java.lang.String, java.lang.String, java.io.File)
  
  Specified by:
  
  putObjectStream in interface OdilonClient
  
  Parameters:
  
  bucketName - Bucket name
  
  objectName - Object name
  
  stream -
  
  fileName -
  
  size -
  
  Returns:
  
  Throws:
  
  ODClientException
- isValidObjectName
  
  public boolean isValidObjectName(String objectName)
  
  Description copied from interface: OdilonClient
  Returns true if the String objectName is a valid name for an Odilon object
  
  objectName length less or equal to SharedConstant.MAX_OBJECT_CHARS
  
  objectName must match Java Regular expression SharedConstant.object_valid_regex
  
  Informally speaking: object names can not have slash (/) or backslash (\)
  
  Examples of invalid object names:
  
  2023/11/349460828-7.2.a.3.implementacion.pdf
  
  2021/9/346049478-roses-2191636
  
  Examples of valid object names:
  
  1-documento rio-90876
  
  2023-6-346227578-Quinquela-773x458.jpeg
  
  2023-11-349460978-compliance-basic.png.enc
  Specified by:
  
  isValidObjectName in interface OdilonClient
  
  Parameters:
  
  objectName - can not be null
  
  Returns:
  
  true if the objectName is a valid Odilon Object name
- putObjectStream
  
  public io.odilon.model.ObjectMetadata putObjectStream(String bucketName, String objectName, InputStream stream, Optional<String> fileName, Optional<Long> size, Optional<String> contentType) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Uploads a InputStream to the server. It will create a new object or update it if already exists.
  
  This method calls OdilonClient.putObject(java.lang.String, java.lang.String, java.io.File)
  
  Specified by:
  
  putObjectStream in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  stream -
  
  fileName -
  
  size -
  
  contentType -
  
  Returns:
  
  Throws:
  
  ODClientException
- putObjectStream
  
  public io.odilon.model.ObjectMetadata putObjectStream(String bucketName, String objectName, InputStream stream, Optional<String> fileName, Optional<Long> size, Optional<String> contentType, Optional<List<String>> customTags) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Uploads a File or any other binary stream to the server. It will create a new object or update an existing one.
  
  This method calls OdilonClient.putObject(java.lang.String, java.lang.String, java.io.File)
  
  Specified by:
  
  putObjectStream in interface OdilonClient
  
  Parameters:
  
  bucketName -
  
  objectName -
  
  stream -
  
  fileName -
  
  size -
  
  contentType -
  
  customTags -
  
  Returns:
  
  Throws:
  
  ODClientException
- isAcceptAllCertificates
  
  public boolean isAcceptAllCertificates()
  
  Specified by:
  
  isAcceptAllCertificates in interface OdilonClient
- isSSL
  
  public boolean isSSL()
  
  Specified by:
  
  isSSL in interface OdilonClient
- putObject
  
  public io.odilon.model.ObjectMetadata putObject(String bucketName, String objectName, File file) throws ODClientException
  Uploads the File file to the server
  Example:
  String endpoint = "http://localhost"; // default port int port = 9234; // default credentials String accessKey = "odilon"; String secretKey = "odilon"; String bucketName = "demo_bucket"; String objectName1 = "demo_object1"; String objectName2 = "demo_object2"; File file1 = new File("test1.pdf"); File file2 = new File("test2.pdf"); // put two objects in the bucket // the bucket must exist before sending the object, // and object names must be unique for that bucket OdilonClient client = new ODClient(endpoint, port, accessKey, secretKey); client.putObject(bucketName, objectName1, file1); client.putObject(bucketName, objectName2, file2);
  Specified by:
  
  putObject in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  file - can not be null, file.exists() must be true, file.isDirectory() must be false, Files.isRegularFile(file.toPath()) must be true Example:
  String endpoint = "http://localhost"; int port = 9234; String accessKey = "odilon"; String secretKey = "odilon"; // OdilonClient is the interface, ODClient is the implementation OdilonClient client = new ODClient(endpoint, port, accessKey, secretKey); File dir = new File("directoryToUpload"); String bucketName = "bucket-demo"; // upload all Files from directory for (File file:dir.listFiles()) { if (!file.isDirectory()) { String objectName = fi.getName()+"-"+String.valueOf(Double.valueOf((Math.abs(Math.random()*100000))).intValue()); getClient().putObject(bucketName, objectName, fi); } }
  
  Returns:
  
  ObjectMetadata of the Object created or updated
  
  Throws:
  
  ODClientException
  
  See Also:
  
  Sample PutObject program in GitHub
- putObject
  
  public io.odilon.model.ObjectMetadata putObject(String bucketName, String objectName, Optional<List<String>> customTags, File file) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Uploads a File or any other binary stream to the server. It will create a new object or update an existing one.
  
  This method does the same as OdilonClient.putObject(java.lang.String, java.lang.String, java.io.File)
  but with a local File instead of an InputStream
  
  Specified by:
  
  putObject in interface OdilonClient
  
  Parameters:
  
  bucketName -
  
  objectName -
  
  customTags - Optional List of user defined tags
  
  file -
  
  Returns:
  
  Throws:
  
  ODClientException
- putObjectStream
  
  public io.odilon.model.ObjectMetadata putObjectStream(String bucketName, String objectName, InputStream stream, String fileName, String contentType) throws ODClientException
  
  Description copied from interface: OdilonClient
  Uploads a File or any other binary stream to the server. It will create a new object or update an existing one.
  
  Odilon stores objects using a flat structure of containers called Buckets.
  A bucket is like a folder, it just contains binary objects, potentially a very large number.
  Every object contained by a bucket has a unique ObjectName in that bucket; therefore, the pair BucketName + ObjectName is a Unique ID for each object in Odilon.
  
  Uploading a File requires the Bucket to exist and the ObjectName to be unique for that bucket.
  
  If the objectName does not exist in the bucket, the server will create a new object, if the objectName exists in the bucket the server will update the object with the new binary data. in this case, if the server has Version Control enabled it will make a new version and the previous version of the object will not be deleted. If the server does not have Version Control enabled, the former version will be discarded.
  
  Objects can optionally be uploaded with one or more user defined tags (String), for example to store a local id with the file uploaded
  
  Odilon client closes the InputStream after sending the data to the server. However, if an Exception other than ODClientException is thrown by this method, the InputStream may not have been closed.
  
  Therefore callers must always attempt to close the InputStream
  Example:
  File file = new File("test.pdf"); String bucketName = "bucket-demo"; String objectName = file.getName(); try (InputStream inputStream = new BufferedInputStream(new FileInputStream(file))){ client.putObjectStream(bucketName,objectName,inputStream,Optional.of(file.getName()),Optional.empty()); } catch (ODClientException e) { System.out.println( "HTTP status -> " + String.valueOf(e.getHttpStatus())+ " | ErrorMsg -> " + e.getMessage() + " Odilon Error Code -> " + String.valueOf(e.getErrorCode()) ); } catch (FileNotFoundException | IOException e1) { System.out.println(e1.getMessage()); }
  Specified by:
  
  putObjectStream in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  stream - can not be null
  
  fileName -
  
  contentType -
  
  Returns:
  
  ObjectMetadata of the Object created or updated
  
  Throws:
  
  ODClientException
- listObjects
  
  public io.odilon.model.list.ResultSet<io.odilon.model.list.Item<io.odilon.model.ObjectMetadata>> listObjects(io.odilon.model.Bucket bucket) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Lists the objects in the Bucket.
  
  see OdilonClient.listObjects(java.lang.String, java.util.Optional<java.lang.String>, java.util.Optional<java.lang.Integer>)
  
  Specified by:
  
  listObjects in interface OdilonClient
  
  Parameters:
  
  bucket - can not be null
  
  Returns:
  
  ResulSet of Items
  
  Throws:
  
  ODClientException
- listObjects
  
  public io.odilon.model.list.ResultSet<io.odilon.model.list.Item<io.odilon.model.ObjectMetadata>> listObjects(String bucketName) throws ODClientException
  Item is a wrapper for Lists and other Iterable structures of T where some elements may not be a T but an error.
  T must be Serializable
  Example list all bucket's objects:
  try { ResultSet<Item<ObjectMetadata>> resultSet = client.listObjects(bucket.getName()); while (resultSet.hasNext()) { Item item = resultSet.next(); if (item.isOk()) System.out.println("ObjectName:" + item.getObject().objectName + " | file: " + item.getObject().fileName); else System.out.println(item.getErrorString()); } } catch (ODClientException e) { System.out.println(String.valueOf(e.getHttpStatus()) + " " + e.getMessage() + " " + String.valueOf(e.getErrorCode())); }
  Specified by:
  
  listObjects in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  Returns:
  
  Throws:
  
  ODClientException
- listObjects
  
  public io.odilon.model.list.ResultSet<io.odilon.model.list.Item<io.odilon.model.ObjectMetadata>> listObjects(String bucketName, String prefix) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Lists the objects in the Bucket.
  
  see OdilonClient.listObjects(java.lang.String, java.util.Optional<java.lang.String>, java.util.Optional<java.lang.Integer>)
  
  Specified by:
  
  listObjects in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  prefix -
  
  Returns:
  
  Throws:
  
  ODClientException
- listObjects
  
  public io.odilon.model.list.ResultSet<io.odilon.model.list.Item<io.odilon.model.ObjectMetadata>> listObjects(String bucketName, Optional<String> prefix, Optional<Integer> pageSize) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Lists the objects in the Bucket.
  
  ResultSet
  Item <ObjectMetadata> can contain:
  it item.isOk() -> a ObjectMetadata .
  otherwise -> or an String with an error
  
  If prefix is not Optional.empty() the list will include only objects where the objectName starts with the prefix.
  pageSize is the number of items retrieved by each call to the server, if the value is Optional.empty() the client will use the default pageSize value.
  Specified by:
  
  listObjects in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  prefix -
  
  pageSize -
  
  Returns:
  
  ResultSet<Item<ObjectMetadata>> . ResultSet is Iterable Item if ok() contain a instance of ObjectMetadata, otherwise a error() returns a String with the error
  Example list all bucket's objects:
  try { ResultSet<Item <ObjectMetadata>> resultSet = client.listObjects(bucket.getName()); while (resultSet.hasNext()) { Item item = resultSet.next(); if (item.isOk()) System.out.println("ObjectName:" + item.getObject().objectName + " | file: " + item.getObject().fileName); else System.out.println(item.getErrorString()); } } catch (ODClientException e) { System.out.println( "HTTP status -> " + String.valueOf(e.getHttpStatus())+ " | ErrorMsg -> " + e.getMessage() + " Odilon Error Code -> " + String.valueOf(e.getErrorCode()) ); } </p>
  
  Throws:
  
  ODClientException
- listBuckets
  
  public List<io.odilon.model.Bucket> listBuckets() throws ODClientException
  Returns all buckets, sorted alphabetically
  
  Example:
  
  List<Bucket> bucketList = odilonClient.listBuckets(); for (Bucket bucket : bucketList) { System.out.println(bucket.creationDate() + ", " + bucket.name()); }
  Specified by:
  
  listBuckets in interface OdilonClient
  
  Returns:
  
  List of buckets
  
  Throws:
  
  ODClientException
- getObjectMetadataPreviousVersionAll
  
  public List<io.odilon.model.ObjectMetadata> getObjectMetadataPreviousVersionAll(String bucketName, String objectName) throws ODClientException
  
  Returns all previous versions of an Object, sorted by version number
  
  Specified by:
  
  getObjectMetadataPreviousVersionAll in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  Returns:
  
  List of ObjectMetadata sorted by version number
  
  Throws:
  
  ODClientException
- isEmpty
  
  public boolean isEmpty(String bucketName) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Returns true if the bucket has no Objects, otherwise false
  
  Specified by:
  
  isEmpty in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  Returns:
  
  true if the bucket has no Objects Throws ODClientException if bucketName is not an existing Bucket
  the http error code ODHttpStatus.NOT_FOUND and Odilon's error code ErrorCode.BUCKET_NOT_EXISTS)
  
  Throws:
  
  ODClientException
- existsBucket
  
  public boolean existsBucket(String bucketName) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Returns true if a bucket with name bucketName exists
  
  Specified by:
  
  existsBucket in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  Returns:
  
  true if the bucket exists in the Server
  
  Throws:
  
  ODClientException
- getBucket
  
  public io.odilon.model.Bucket getBucket(String bucketName) throws ODClientException
  
  Description copied from interface: OdilonClient
  Returns the Bucket
  
  It will throw a ODClientException if the bucket does not exist.
  
  Example:
  
  if (odilonClient.existsBucket("test-bucket")( { Bucket bucket = odilonClient.getBucket("test-bucket"); System.out.println("bucket name ->" + bucket.getName() ); System.out.println("bucket created ->" + bucket.getCreationDate().toString() ); }
  Specified by:
  
  getBucket in interface OdilonClient
  
  Parameters:
  
  bucketName - Bucket name
  
  Returns:
  
  Bucket Throws ODClientException
  BucketName is not an existing Bucket -> ODHttpStatus.NOT_FOUND with error code ErrorCode.BUCKET_NOT_EXISTS
  
  Throws:
  
  ODClientException
- createBucket
  
  public void createBucket(String bucketName) throws ODClientException
  
  Description copied from interface: OdilonClient
  Creates a new Bucket.
  
  Odilon stores objects using a flat structure of containers called Buckets. A bucket is like a folder, it just contains binary objects, potentially a very large number. Every object contained by a bucket has a unique ObjectName in that bucket; therefore, the pair BucketName + ObjectName is a Unique ID for each object in Odilon.
  
  The bucket must not exist, if it exists the method will throw a ODClientException.
  bucketName length must be lower or equal to SharedConstant.MAX_BUCKET_CHARS and
  match the regular expression SharedConstant.bucket_valid_regex (see OdilonClient.isValidBucketName(java.lang.String))
  Example:
  try { String bucketName = "bucket-demo"; // check if the bucket exists, if not create it if (client.existsBucket(bucketName)) System.out.println("bucket already exists ->" + bucketName ); else client.createBucket(bucketName); } catch (ODClientException e) { System.out.println( "HTTP status -> " + String.valueOf(e.getHttpStatus())+ " | ErrorMsg -> " + e.getMessage() + " Odilon Error Code -> " + String.valueOf(e.getErrorCode()) ); }
  Specified by:
  
  createBucket in interface OdilonClient
  
  Parameters:
  
  bucketName - Bucket name Throws ODClientException if the bucket already exists (error code ErrorCode.OBJECT_ALREADY_EXIST)
  
  Throws:
  
  ODClientException
- renameBucket
  
  public void renameBucket(String bucketName, String newBucketName) throws ODClientException
  
  Description copied from interface: OdilonClient
  Renames a Bucket.
  
  The new bucket name must not be used by another bucket
  Example:
  try { String bucketName = "bucket-demo"; // check if the bucket exists, if not create it if (client.existsBucket(bucketName)) System.out.println("bucket already exists ->" + bucketName ); else client.createBucket(bucketName); // rename bucket to "bucket-demo-renamed" client.renameBucket(bucketName, "bucket-demo-renamed"); } catch (ODClientException e) { System.out.println( "HTTP status -> " + String.valueOf(e.getHttpStatus())+ " | ErrorMsg -> " + e.getMessage() + " Odilon Error Code -> " + String.valueOf(e.getErrorCode()) ); }
  Specified by:
  
  renameBucket in interface OdilonClient
  
  Parameters:
  
  bucketName - existing Bucket name
  
  newBucketName - new Bucket name Throws ODClientException if the bucket does not exist (ErrorCode.BUCKET_NOT_EXISTS) if newBucketName is already used by another bucket (ErrorCode.OBJECT_ALREADY_EXIST)
  
  Throws:
  
  ODClientException
- addServiceRequest
  
  public void addServiceRequest(String requestClass) throws ODClientException
  
  Parameters:
  
  requestClass -
  
  Throws:
  
  ODClientException
- deleteBucket
  
  public void deleteBucket(String bucketName) throws ODClientException
  
  Description copied from interface: OdilonClient
  Deletes a Bucket. The bucket must be empty to be deleted
  
  Example:
  
  try { // deletes all buckets that have no objects for (Bucket bucket:odilonClient.listBuckets()) { if (odilonClient.isEmpty(bucket.getName())) { odilonClient.deleteBucket(bucket.getName()); } } } catch (ODClientException e) { System.out.println( "HTTP status -> " + String.valueOf(e.getHttpStatus())+ " | ErrorMsg -> " + e.getMessage() + " Odilon Error Code -> " + String.valueOf(e.getErrorCode()) ); }
  Specified by:
  
  deleteBucket in interface OdilonClient
  
  Parameters:
  
  bucketName - Bucket name Throws ODHttpStatus.NOT_FOUND if Bucket does not exist, with error code ErrorCode.BUCKET_NOT_EXISTS
  ODHttpStatus.CONFLICT if Bucket does not exist, with error code ErrorCode.BUCKET_NOT_EMPTY
  
  Throws:
  
  ODClientException
- deleteObject
  
  public void deleteObject(String bucketName, String objectName) throws ODClientException
  Removes an object from a bucket.
  
  Example:
  
  odilonClient.deleteObject("my-bucketname", "my-objectname");
  Specified by:
  
  deleteObject in interface OdilonClient
  
  Parameters:
  
  bucketName - Bucket name
  
  objectName - Object name in the bucket
  
  Throws:
  
  ODClientException
- deleteObjectAllVersions
  
  public void deleteObjectAllVersions(String bucketName, String objectName) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Deletes all the Object's previous versions, it does not delete the object current version (head version).
  
  After calling this method the Object will have only the head version.
  
  Specified by:
  
  deleteObjectAllVersions in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  Throws:
  
  ODClientException
- restoreObjectPreviousVersions
  
  public void restoreObjectPreviousVersions(String bucketName, String objectName) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Restores the previous version of the Object and deletes current version.
  
  If the object does not have any previous versions, it throws an ODClientException
  Specified by:
  
  restoreObjectPreviousVersions in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null Throws ODClientException
  
  The server does not have Version Control enabled -> ODHttpStatus#METHOD_NOT_ALLOWED, ErrorCode#API_NOT_ENABLED
  
  The Object does not have a previous version (i.e. current version is version 0) -> ODHttpStatus#NOT_FOUND, ErrorCode#OBJECT_NOT_FOUND
  
  All the object's previous version has been deleted via OdilonClient.deleteAllBucketVersions(java.lang.String) or OdilonClient.deleteObjectAllVersions(java.lang.String,java.lang.String) -> ODHttpStatus#NOT_FOUND, ErrorCode#OBJECT_NOT_FOUND
  
  Other, unexpected causes -> ODHttpStatus#INTERNAL_SERVER_ERROR, ErrorCode#INTERNAL_ERROR
  
  Throws:
  
  ODClientException
- deleteAllBucketVersions
  
  public void deleteAllBucketVersions(String bucketName) throws ODClientException
  
  Description copied from interface: OdilonClient
  Deletes all the previous versions of all the Objects in the Bucket.
  Note that it does not delete the current version of the objects (called head version).
  
  This method is sometimes used to free disk in the server
  Async execution
  This method returns immediately after sending the command to the server, which processes the task asynchronously. The async command is atomic on each object but not globally, which means that until it finishes some objects can still have versions.
  
  Example:
  
  try { Bucket bucket = odilonClient.getBucket("test-version-control"); odilonClient.deleteAllBucketVersions(bucket.getName()); } catch (ODClientException e) { System.out.println( "HTTP status -> " + String.valueOf(e.getHttpStatus())+ " | ErrorMsg -> " + e.getMessage() + " Odilon Error Code -> " + String.valueOf(e.getErrorCode()) ); }
  Specified by:
  
  deleteAllBucketVersions in interface OdilonClient
  
  Parameters:
  
  bucketName - Bucket name Throws ODClientException
  Bucket does not exist -> ODHttpStatus.NOT_FOUND with error code ErrorCode.BUCKET_NOT_EXISTS
  Server does not have Version Control enabled -> ODHttpStatus.METHOD_NOT_ALLOWED with error code ErrorCode.API_NOT_ENABLED Version Control not enabled
  
  Throws:
  
  ODClientException
- systemInfo
  
  public io.odilon.model.SystemInfo systemInfo() throws ODClientException
  
  Returns SystemInfo
  
  Specified by:
  
  systemInfo in interface OdilonClient
  
  Returns:
  
  SystemInfo
  
  Throws:
  
  ODClientException
- isVersionControl
  
  public boolean isVersionControl() throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Checks if the server has version control enabled
  
  Specified by:
  
  isVersionControl in interface OdilonClient
  
  Returns:
  
  true if the server has version control enabled
  
  Throws:
  
  ODClientException
- isHTTPS
  
  public boolean isHTTPS()
  
  Specified by:
  
  isHTTPS in interface OdilonClient
- metrics
  
  public io.odilon.model.MetricsValues metrics() throws ODClientException
  
  Description copied from interface: OdilonClient
  Returns an instance of MetricsValues with info related to the activity of the server
  
  They are counters of events and meters that measure events per second in a 1m 5m and 15m windows
  
  Counter A counter is just a gauge for an AtomicLong instance. You can increment or decrement its value.
  
  Meter A meter measures the rate of events over time (e.g., “requests per second”). In addition to the mean rate, meters also track 1-, 5-, and 15-minute moving averages.
  
  See https://metrics.dropwizard.io/4.2.0
  Example:
  
  cacheObjectHitCounter -> 1,224
  cacheObjectMissCounter -> 637
  cacheObjectSize -> 475
  decryptFileMeter -> 0.27 0.42 0.24
  encrpytFileMeter -> 0.49 0.67 0.46
  objectCreateCounter -> 475
  objectDeleteCounter -> 0
  objectDeleteVersionCounter -> 0
  objectGetMeter -> 0.55 0.85 0.48
  objectPutMeter -> 0.49 0.67 0.46
  objectUpdateCounter -> 162
  replicaObjectCreate -> 0
  replicaObjectDelete -> 0
  replicaObjectUpdate -> 0
  vaultDecryptMeter -> 0.00 0.00 0.00
  vaultEncryptMeter -> 0.00 0.00 0.00
  Specified by:
  
  metrics in interface OdilonClient
  
  Returns:
  
  MetricsValues
  
  Throws:
  
  ODClientException
- ping
  
  public String ping()
  Returns the String "ok" or a String with the error reported by the Server. If the client can not connect to the Server, the method returns a message "can not connect"
  Example:
  
  String pingResult = odilonClient.ping(); if (!pingResult.equals("ok")) { System.out.println( "Server error -> " + pingResult)); }
  Specified by:
  
  ping in interface OdilonClient
  
  Returns:
  
  String "ok" or the error reported by the Server.
- getPresignedObjectUrl
  
  public String getPresignedObjectUrl(String bucketName, String objectName, Optional<Integer> expires, Map<String,String> reqParams) throws ODClientException
  
  A presigned URL is a way to grant temporary access to an Object, for example in an HTML webpage. It remains valid for a limited period of time which is specified when the URL is generated.
  
  Throws:
  
  ODClientException
- getPresignedObjectUrl
  
  public String getPresignedObjectUrl(String bucketName, String objectName, Optional<Integer> expires) throws ODClientException
  
  A presigned URL is a way to grant temporary access to an Object, for example in an HTML webpage. It remains valid for a limited period of time which is specified when the URL is generated.
  
  Specified by:
  
  getPresignedObjectUrl in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  expires - duration in seconds for the url to be valid
  
  Returns:
  
  temporary url to download the file without authentication
  
  Throws:
  
  ODClientException
- getPresignedObjectUrl
  
  public String getPresignedObjectUrl(String bucketName, String objectName) throws ODClientException
  
  Returns an presigned URL to download the binary object with default expiry time.
  Default expiry time is 7 days in seconds.
  
  Specified by:
  
  getPresignedObjectUrl in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  Returns:
  
  temporary url to download the file without authentication
  
  Throws:
  
  ODClientException
- existsObject
  
  public boolean existsObject(String bucketName, String objectName) throws ODClientException, IOException
  
  Description copied from interface: OdilonClient
  
  Checks for the existence of an Object.
  
  Note that if the Bucket does not exist, the method does not throw an Exception, it returns false
  
  Specified by:
  
  existsObject in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  Returns:
  
  true if the Object exist Throws ODClientException, IOException
  
  Throws:
  
  ODClientException
  
  IOException
- hasVersions
  
  public boolean hasVersions(String bucketName, String objectName) throws ODClientException, IOException
  
  Description copied from interface: OdilonClient
  
  Returns true if the Object has previous versions, ie. at least there is one version older than the head version (in which case the head version must be greater than 0)
  
  Specified by:
  
  hasVersions in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  Returns:
  
  true if the Object has more versions than the head version (ie. the head version must be greater than 0) Throws ODClientException Throws IOException
  
  Throws:
  
  ODClientException
  
  IOException
- getObjectMetadata
  
  public io.odilon.model.ObjectMetadata getObjectMetadata(String bucketName, String objectName) throws ODClientException
  Returns ObjectMetadata of given object in given bucket.
  Example:
  
  ObjectMetadata meta = odilonClient.getObjectMetadata("my-bucketname", "my-objectname"); System.out.println(meta.toString()));
  Specified by:
  
  getObjectMetadata in interface OdilonClient
  
  Parameters:
  
  bucketName - Bucket name
  
  objectName - Object name in the bucket
  
  Returns:
  
  ObjectMetadata from server Throws ODClientException if object does not exist
  
  Throws:
  
  ODClientException
- getObjectMetadataPreviousVersion
  
  public io.odilon.model.ObjectMetadata getObjectMetadataPreviousVersion(String bucketName, String objectName) throws ODClientException
  Returns ObjectMetadata of previous version
  Example:
  
  ObjectMetadata meta = odilonClient.getObjectMetadata("my-bucketname", "my-objectname"); System.out.println(meta.toString()));
  Specified by:
  
  getObjectMetadataPreviousVersion in interface OdilonClient
  
  Parameters:
  
  bucketName - Bucket name.
  
  objectName - Object name in the bucket.
  
  Returns:
  
  Throws:
  
  ODClientException
- getObject
  
  public InputStream getObject(String bucketName, String objectName) throws ODClientException
  Gets entire object's data as InputStream in given bucket. The InputStream must be closed after use else the connection will remain open.
  Example:
  InputStream stream = OdilonClient.getObject("my-bucketname", "my-objectname"); byte[] buf = new byte[16384]; int bytesRead; while ((bytesRead = stream.read(buf, 0, buf.length)) >= 0) { System.out.println(new String(buf, 0, bytesRead)); } stream.close();
  Specified by:
  
  getObject in interface OdilonClient
  
  Parameters:
  
  bucketName - Bucket name
  
  objectName - Object name in the bucket
  
  Returns:
  
  InputStream containing the object data.
  
  Throws:
  
  ODClientException
- getObjectPreviousVersion
  
  public InputStream getObjectPreviousVersion(String bucketName, String objectName) throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Returns the binary data of the object's previous version or null if there is no previous version.
  
  Specified by:
  
  getObjectPreviousVersion in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  Returns:
  
  ObjectMetadata of the object's previous version
  
  Throws:
  
  ODClientException
- getObjectVersion
  
  public InputStream getObjectVersion(String bucketName, String objectName, int version) throws ODClientException
  
  get InputStream of the version passed as parameter, null if head is version 0 parameter is non existent or previous versions were wiped
  
  Specified by:
  
  getObjectVersion in interface OdilonClient
  
  Parameters:
  
  bucketName - can not be null
  
  objectName - can not be null
  
  version -
  
  Returns:
  
  Throws:
  
  ODClientException
- getObject
  
  public void getObject(String bucketName, String objectName, String fileName) throws ODClientException, IOException
  Gets object's data and stores it to given file name.
  Example:
  
  odilonClient.getObject("my-bucketname", "my-objectname", "photo.jpg");
  Specified by:
  
  getObject in interface OdilonClient
  
  Parameters:
  
  bucketName - Bucket name.
  
  objectName - Object name in the bucket.
  
  fileName - file name.
  
  Throws:
  
  ODClientException
  
  IOException
- setTimeout
  
  public void setTimeout(long connectTimeoutMilliseconds, long writeTimeoutMilliseconds, long readTimeoutMilliseconds)
  Sets HTTP connect, write and read timeouts. A value of 0 means no timeout, otherwise values must be between 1 and Integer.MAX_VALUE when converted to milliseconds.
  Example:
  
  odilonClient.setTimeout(TimeUnit.SECONDS.toMillis(10), TimeUnit.SECONDS.toMillis(10), TimeUnit.SECONDS.toMillis(30));
  Specified by:
  
  setTimeout in interface OdilonClient
  
  Parameters:
  
  connectTimeoutMilliseconds - HTTP connect timeout in milliseconds.
  
  writeTimeoutMilliseconds - HTTP write timeout in milliseconds.
  
  readTimeoutMilliseconds - HTTP read timeout in milliseconds.
- ignoreCertCheck
  
  public void ignoreCertCheck() throws NoSuchAlgorithmException, KeyManagementException
  Ignores check on server certificate for HTTPS connection.
  Example:
  
  odilonClient.ignoreCertCheck();
  Throws:
  
  NoSuchAlgorithmException
  
  KeyManagementException
- close
  
  public void close() throws ODClientException
  
  Description copied from interface: OdilonClient
  
  Shutdown Isn't Necessary because the threads and connections that are held will be released automatically if they remain idle
  
  Specified by:
  
  close in interface OdilonClient
  
  Throws:
  
  ODClientException
- isValidBucketName
  
  public boolean isValidBucketName(String name)
  
  Description copied from interface: OdilonClient
  Returns true if the String bucketName is a valid name for an Odilon Bucket
  
  bucketName length less or equal to SharedConstant.MAX_BUCKET_CHARS
  
  bucketName must match Java Regular expression SharedConstant.bucket_valid_regex
  Informally speaking: letters A to Z and/or a to z, numbers, and/or - or _
  Specified by:
  
  isValidBucketName in interface OdilonClient
  
  Parameters:
  
  name - can not be null
  
  Returns:
  
  true if the bucketName is a valid Odilon Bucket name
- traceOn
  
  public void traceOn(OutputStream traceStream)
  
  Description copied from interface: OdilonClient
  
  enabled printing the request-response raw info to a stream
  
  Specified by:
  
  traceOn in interface OdilonClient
- traceOff
  
  public void traceOff() throws IOException
  
  Disables HTTP call tracing previously enabled.
  Specified by:
  
  traceOff in interface OdilonClient
  
  Throws:
  
  IOException - upon connection error
  
  See Also:
  
  traceOn(java.io.OutputStream)
- toJSON
  
  public String toJSON()
- toString
  
  public String toString()
  
  Overrides:
  
  toString in class Object
- created
  
  public OffsetDateTime created()
- setChunkSize
  
  public void setChunkSize(int chunkSize)
  
  Specified by:
  
  setChunkSize in interface OdilonClient
- getChunkSize
  
  public int getChunkSize()
  
  Specified by:
  
  getChunkSize in interface OdilonClient
- setCharset
  
  public void setCharset(String c)
  
  Specified by:
  
  setCharset in interface OdilonClient
  
  Parameters:
  
  c -
- getCharset
  
  public String getCharset()
  
  Specified by:
  
  getCharset in interface OdilonClient
  
  Returns:
  
  Charsert "UTF-8" is the default value.
- getUrl
  
  public String getUrl()
  
  Description copied from interface: OdilonClient
  
  Returns the url of the Odilon server
  
  Specified by:
  
  getUrl in interface OdilonClient
  
  Returns:
  
  server url (without the port)
- getObjectMapper
  
  protected com.fasterxml.jackson.databind.ObjectMapper getObjectMapper()

Class ODClient

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

DEFAULT_CONNECTION_TIMEOUT

DEFAULT_USER_AGENT

Constructor Details

ODClient

ODClient

ODClient

Method Details

setPresignedUrl

setPresignedUrl

setPresignedUrl

putObjectStream

putObjectStream

isValidObjectName

putObjectStream

putObjectStream

isAcceptAllCertificates

isSSL

putObject

putObject

putObjectStream

listObjects

listObjects

listObjects

listObjects

listBuckets

getObjectMetadataPreviousVersionAll

isEmpty

existsBucket

getBucket

createBucket

renameBucket

addServiceRequest

deleteBucket

deleteObject

deleteObjectAllVersions

restoreObjectPreviousVersions

deleteAllBucketVersions

systemInfo

isVersionControl

isHTTPS

metrics

ping

getPresignedObjectUrl

getPresignedObjectUrl

getPresignedObjectUrl

existsObject

hasVersions

getObjectMetadata

getObjectMetadataPreviousVersion

getObject

getObjectPreviousVersion

getObjectVersion

getObject

setTimeout

ignoreCertCheck

close

isValidBucketName

traceOn

traceOff

toJSON

toString

created

setChunkSize

getChunkSize

setCharset

getCharset

getUrl

getObjectMapper