Package org.yamcs.protobuf

Class AbstractBucketsApi<T>

  • All Implemented Interfaces:
    Api<T>
    Direct Known Subclasses:
    BucketsApiClient
    public abstract class AbstractBucketsApi<T>
extends Object
implements Api<T>
      Methods related to object storage.
 
  Buckets represent a simple mechanism for storing user objects (binary data
  chunks such as images, monitoring lists, displays...) together with some
  metadata. Buckets can be created globally or asociated with an instance.
 
  The metadata is represented by simple (key,value) pairs where both key and
  value are strings.
 
  By default each user has a bucket named ``user.username`` which can be used
  without extra privileges. Additional buckets may be created and used if the
  user has the required privileges. The user bucket will be created
  automatically when the user tries to access it.
 
  Buckets can be created at global level or at instance level. 
  The following limitations are implemented in order to prevent disk over
  consumption and keep the service responsive:
 
  *   The maximum size of an upload including data and metadata is 5MB.
  *   The maximum number of objects in one bucket is 1000.
  *   The maximum size of an bucket 100MB (counted as the sum of the size of
      the objects within the bucket).
  *   The maximum size of the metadata is 16KB (counted as the sum of the
      length of the keys and values).

    • Constructor Detail

      • AbstractBucketsApi

        public AbstractBucketsApi()

    • Method Detail

      • createBucket

        public abstract void createBucket​(T ctx,
                                  CreateBucketRequest request,
                                  Observer<com.google.protobuf.Empty> observer)
          Create a bucket

      • deleteBucket

        public abstract void deleteBucket​(T ctx,
                                  DeleteBucketRequest request,
                                  Observer<com.google.protobuf.Empty> observer)
          Delete a bucket
 
  Deleting a bucket means also deleting all objects that are part of it.

      • getObject

        public abstract void getObject​(T ctx,
                               GetObjectRequest request,
                               Observer<HttpBody> observer)
          Get an object
 
  The body of the response represents the object data. The ``Content-Type``
  header is set to the content type of the object specified when uploading
  the object. If no ``Content-Type`` was specified when creating the object,
  the ``Content-Type`` of the response is set to
  ``application/octet-stream``.

      • uploadObject

        public abstract void uploadObject​(T ctx,
                                  UploadObjectRequest request,
                                  Observer<com.google.protobuf.Empty> observer)
          Upload an object
 
  .. rubric:: Simple upload
  
  In case of simple upload, the objectName has to be specified as part of the URL
  and the ``Content-Type header`` has to be set to the type of the object. The body
  of the request is the object data.
  
  
  .. rubric:: Form upload
  
  The form based upload can be used to upload an object from an HTML form. In this
  case the Content-Type of the request is set to ``multipart/form-data``, and the
  body will contain at least one part which is the object data. This part includes
  a filename which is used as the object name as well as a ``Content-Type`` header.
  The name attribute for the file part is ignored.
  Additional parts (which do not specify a filename) will be used as metadata: the
  name is specified as part of the ``Content-Disposition`` and the value is the body
  of the part.
  
  This can be tested with curl using the ``-F`` option.
  
  
  .. rubric:: Example
  .. code-block:: http
  
      POST /api/buckets/_global/my_bucket HTTP/1.1
      Host: localhost:8090
      User-Agent: curl/7.58.0
      Accept: */*
      Content-Length: 1090
      Content-Type: multipart/form-data; boundary=------------------------7109c709802f7ae4
  
      --------------------------7109c709802f7ae4
      Content-Disposition: form-data; name="file"; filename="object/name"
      Content-Type: text/plain
  
      [object data]
      --------------------------7109c709802f7ae4
      Content-Disposition: form-data; name="name1"
  
      value1
      --------------------------7109c709802f7ae4
      Content-Disposition: form-data; name="name2"
  
      value2
      --------------------------7109c709802f7ae4--
  
  
  This will create an object named ``object/name`` with two metadata properties:
  
  .. code-block:: json
  
      {
          "name1": "value1",
          "name2": "value2"
      }

      • deleteObject

        public abstract void deleteObject​(T ctx,
                                  DeleteObjectRequest request,
                                  Observer<com.google.protobuf.Empty> observer)
          Delete an object

      • getDescriptorForType

        public final com.google.protobuf.Descriptors.ServiceDescriptor getDescriptorForType()
        Specified by:
        getDescriptorForType in interface Api<T>

      • getRequestPrototype

        public final com.google.protobuf.Message getRequestPrototype​(com.google.protobuf.Descriptors.MethodDescriptor method)
        Specified by:
        getRequestPrototype in interface Api<T>

      • getResponsePrototype

        public final com.google.protobuf.Message getResponsePrototype​(com.google.protobuf.Descriptors.MethodDescriptor method)
        Specified by:
        getResponsePrototype in interface Api<T>

      • callMethod

        public final void callMethod​(com.google.protobuf.Descriptors.MethodDescriptor method,
                             T ctx,
                             com.google.protobuf.Message request,
                             Observer<com.google.protobuf.Message> future)
        Specified by:
        callMethod in interface Api<T>

      • callMethod

        public final Observer<com.google.protobuf.Message> callMethod​(com.google.protobuf.Descriptors.MethodDescriptor method,
                                                              T ctx,
                                                              Observer<com.google.protobuf.Message> future)
        Specified by:
        callMethod in interface Api<T>