Package io.odilon.client

Interface OdilonClient

  • All Known Implementing Classes:
    ODClient
    public interface OdilonClient

    Inteface of a Odilon Object Storage client.
    See https://Odilon.io

    See Implementation of this Interface: ODClient

    • Method Detail

      • createBucket

        void createBucket​(String bucketName)
           throws ODClientException

        bucketName length must be lower or equal to SharedConstant.MAX_BUCKET_CHARS and match the regular expression SharedConstant.bucket_valid_regex (see 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( String.valueOf(e.getHttpStatus())+ " " + e.getMessage() + " " + String.valueOf(e.getErrorCode()) );
 }
        Parameters:
        bucketName - Bucket name
        Throws:
        ODClientException - if the bucket already exists (error code ErrorCode.OBJECT_ALREADY_EXIST)

      • listBuckets

        List<io.odilon.model.Bucket> listBuckets()
                                  throws ODClientException

        Returns all buckets, sorted alphabetically

        Example:

        
 
 OdilonClient odilonClient = new ODClient(url, port, accessKey, secretKey);
 
 List<Bucket> bucketList = odilonClient.listBuckets();
 for (Bucket bucket : bucketList) {
   	System.out.println(bucket.creationDate() + ", " + bucket.name());
 }

        Returns:
        List of Buckets
        Throws:
        ODClientException

      • isValidBucketName

        boolean isValidBucketName​(String bucketName)
                   throws ODClientException

        • Max length: SharedConstant.MAX_BUCKET_CHARS
        • Regular expression that must match: SharedConstant.bucket_valid_regex

        Parameters:
        bucketName - Bucket name
        Returns:
        whether the bucketName is a valid Odilon bucket name
        Throws:
        ODClientException

      • getBucket

        io.odilon.model.Bucket getBucket​(String bucketName)
                          throws ODClientException

        Returns the Bucket

        Parameters:
        bucketName - Bucket name
        Returns:
        Bucket
        Throws:
        ODClientException - if the Bucket does not exist the error code getErrorCode() returns ErrorCode.BUCKET_NOT_EXISTS

      • deleteBucket

        void deleteBucket​(String bucketName)
           throws ODClientException

        Deletes a bucket. The bucket must be empty to be deleted

        Parameters:
        bucketName - Bucket name
        Throws:
        ODClientException -
        Bucket does not exist -> ODHttpStatus.NOT_FOUND with error code ErrorCode.BUCKET_NOT_EXISTS
        Bucket is not empty -> with error code {@link ErrorCode.BUCKET_NOT_EMPTY}

      • deleteAllBucketVersions

        void deleteAllBucketVersions​(String bucketName)
                      throws ODClientException

        Deletes all Objects' previous versions. It does not delete the current version (called head version).
        This method is sometimes used to free disk in the server

        The method returns immediately after sending the command to the server. The command is processed asynchronously in the server.

        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

      • existsObject

        boolean existsObject​(String bucketName,
                     String objectName)
              throws ODClientException,
                     IOException

        Checks the existence of Object: bucketName, objectName
        Note that if the bucket does not exist, the method does not throw an Exception, it returns false

        Parameters:
        bucketName - Bucket name
        objectName - Object name
        Returns:
        true if the Object exist
        Throws:
        ODClientException
        IOException

      • getObjectMetadata

        io.odilon.model.ObjectMetadata getObjectMetadata​(String bucketName,
                                                 String objectName)
                                          throws ODClientException

        In addition to the binary file, an Object has metadata (called ObjectMetadata) that is returned by some of the API calls. Odilon allows to retrieve Objects individually by bucketName + objectName and also supports to list the contents of a bucket and other simple queries.

        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.

        Parameters:
        bucketName - Bucket name
        objectName - Object name
        Returns:
        Throws:
        ODClientException

      • getPresignedObjectUrl

        String getPresignedObjectUrl​(String bucketName,
                             String objectName,
                             Optional<Integer> expiresInSeconds)
                      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.

        Example: 
        
 this.bucket = getClient().listBuckets().get(0);
		
		 ResultSet<Item<ObjectMetadata>> rs = getClient().listObjects(this.bucket.getName());
		 int counter = 0;
		 while (rs.hasNext() && counter++ < MAX) {
			 Item<ObjectMetadata> item = rs.next();
			 if (item.isOk()) {
				 	ObjectMetadata meta = item.getObject();
 					
 					// by default the link lasts 7 days
					logger.debug(meta.bucketName + " / " + meta.objectName + " (7 days) -> " + getClient().getPresignedObjectUrl(meta.bucketName, meta.objectName));	 
					
					// url valid for 5 minutes 
					logger.debug(meta.bucketName + " / " + meta.objectName + " (5 min) -> " + getClient().getPresignedObjectUrl(meta.bucketName, meta.objectName, Optional<Integer>(Integer.valueOf(60*5)));	 
			 }
		 }
        Parameters:
        bucketName - Bucket name
        objectName - Object name
        expiresInSeconds - duration in seconds for the url to be valid
        Returns:
        temporary url to download the file without authentication
        Throws:
        ODClientException

      • putObject

        io.odilon.model.ObjectMetadata putObject​(String bucketName,
                                         String objectName,
                                         InputStream stream,
                                         String fileName,
                                         String contentType)
                                  throws ODClientException

        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.

        The 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(String.valueOf(e.getHttpStatus())+" " + e.getMessage() +" " + String.valueOf(e.getErrorCode()));
	} catch (FileNotFoundException | IOException e1) {
		System.out.println(e1.getMessage());
	}
        Parameters:
        bucketName - Bucket name
        objectName - Object name
        stream -
        fileName -
        contentType -
        Returns:
        ObjectMetadata of the Object created or updated
        Throws:
        ODClientException

      • deleteObject

        void deleteObject​(String bucketName,
                  String objectName)
           throws ODClientException

        Removes an object from a bucket.

        Example:

        odilonClient.deleteObject("my-bucketname", "my-objectname");

        Parameters:
        bucketName - Bucket name
        objectName - Object name in the bucket
        Throws:
        ODClientException

      • listObjects

        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

        Item <T> 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()) );
	}
        Throws:
        ODClientException

      • ping

        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: 
        {@code 
 String endpoint = "http://localhost";
 int port = 9234;
 String accessKey = "odilon";
 String secretKey = "odilon";
 
 OdilonClient client = new ODClient(endpoint, port, accessKey, secretKey);
 
 String pingResult = odilonClient.ping();
 
 if (!pingResult.equals("ok")) {
   System.out.println( "Server error -> " + pingResult));
 }
        Returns:
        String "ok" or the error reported by the Server.

      • getUrl

        String getUrl()
        Returns:
        server url (without the port)

      • setTimeout

        void setTimeout​(long connectTimeout,
                long writeTimeout,
                long readTimeout)
        ======================================= CLIENT SETTINGS ==========================================

      • traceOn

        void traceOn​(OutputStream traceStream)
        ======================================= DEBUG ==========================================