Using the Outbound Adapter for Cloud Storage

Creating a Business Operation to Use the Adapter

To use the cloud outbound adapter, create a business operation class as follows:

• Your business operation class should extend Ens.BusinessOperationOpens in a new tab.

• In your class, the ADAPTER parameter should equal EnsLib.CloudStorage.OutboundAdapterOpens in a new tab.

• In your class, the INVOCATION parameter should specify the invocation style you want to use, which must be one of the following.

  • Queue means the message is created within one background job and placed on a queue, at which time the original job is released. Later, when the message is processed, a different background job is allocated for the task. This is the most common setting.

  • InProc means the message will be formulated, sent, and delivered in the same job in which it was created. The job will not be released to the sender’s pool until the message is delivered to the target. This is only suitable for special cases.

• Your class should define a message map that includes at least one entry. A message map is an XData block entry that has the following structure:

  XData MessageMap
  {
  <MapItems>
    <MapItem MessageType="messageclass">
      <Method>methodname</Method>
    </MapItem>
    ...
  </MapItems>
  }
  
  

  

• Your class should define all the methods named in the message map. These methods are known as message handlers. Each message handler should have the following signature:

  Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status {
  }

  

  Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class. See Defining Messages.

  To use the adapter, the method code must call methods of the Adapter property of your business operation. See Deleting Blobs and Uploading Blobs.

• For other options and general information, see Defining a Business Operation Class.

The following example shows the general structure that you need:

Class ECLOUD.NewOperation1 Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.CloudStorage.OutboundAdapter";

Parameter INVOCATION = "Queue";

Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
{
  Quit $$$ERROR($$$NotImplemented)
}

XData MessageMap
{
<MapItems>
  <MapItem MessageType="RequestClass">
    <Method>Sample</Method>
  </MapItem>
</MapItems>
}
}

Deleting Blobs

A business operation deletes an blob from cloud storage by calling the DeleteBlob() method of the outbound adapter. The signature of this method is as follows:

method DeleteBlob(bucketName as %String, blobName as %String) as %Status {
}

Where:

• bucketName is the name of the bucket where the blob is stored.

• blobName is the name of the blob.

For example, one of your custom methods could include this:

 Set tSC = ..Adapter.DeleteBlob(..BucketName, request.BlobName)

This code uses the BucketName property to refer to the cloud storage bucket. The name of the blob to delete is taken from the request message.

Uploading Blobs

The outbound adapter provides three different methods for uploading blobs, depending on the source or data type of the data. The signatures of these methods are as follows:

method UploadBlobFromFile(bucketName as %String, blobName as %String, filePath as %String) as %Status {
}

method UploadBlobFromStream(bucketName as %String, blobName as %String, content as %Stream.Object) as %Status {
}

method UploadBlobFromString(bucketName as %String, blobName as %String, content as %String) as %Status {
}

Where:

• bucketName is the name of the bucket where the blob is stored.

• blobName is the name of the blob.

• filePath, used by UploadBlobFromFile(), is the full pathname of the file to be read and uploaded.

• content, used by the other methods, is the data to be uploaded. For UploadBlobFromStream(), this must be an instance of %Stream.ObjectOpens in a new tab. For UploadBlobFromString(), this is a string.

For example, one of your custom methods could include this:

 Set tSC = ..Adapter.UploadBlobFromStream(..BucketName, 
            request.BlobName, request.Content)

Prebuilt Cloud Business Operation

For your convenience, InterSystems provides a simple business operation, EnsLib.CloudStorage.BusinessOperationOpens in a new tab, that demonstrates how to delete a blob and upload a blob from a stream. This sample business operation uses two simple message classes, EnsLib.CloudStorage.DeleteRequestOpens in a new tab and EnsLib.CloudStorage.UploadRequestOpens in a new tab to delete and upload blobs. EnsLib.CloudStorage.BusinessOperationOpens in a new tab includes the property BucketName as described above. The outbound adapter does not include this property, so custom business operations must include it.