Package io.odilon.client

Class ODClient

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 Details

    • DEFAULT_CONNECTION_TIMEOUT

      public static final int DEFAULT_CONNECTION_TIMEOUT
      default network I/O timeout is 15 minutes
      See Also:

    • 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

    • 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
      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
      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
      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:

    • 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
      customTags - Optional List of user defined tags
      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
      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
      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
      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
      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
      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:

    • 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

    • 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()