com.ibm.datapower.wamt.clientAPI
Class Blob

java.lang.Object
  extended by com.ibm.datapower.wamt.clientAPI.Blob

public class Blob
extends java.lang.Object

A simple representation of a Binary Large OBject (BLOB). Blobs are used in the manager to create and hold binary firmware images, DomainVersion images, and DeploymentPolicyVersion images, however the firmware image is the only Blob that will be exposed via the client API. Blobs for domains and deployment policies are handled inside the manager and not exposed via the client API. See URLSource for more information about how to work with Domain and DeploymentPolicy images in the clientAPI.

This class can be instantiated via byte array, URL, or a File. Normally it would seem that a byte array would be easiest, but in the case of a very large binary object (i.e., multiple megabytes), a File or URL are nicer because they lack the need to be loaded into memory at once and thus have a large memory footprint. For that reason, the Blob(File) constructor or Blob(URL) constructor is preferred over the Blob(byte[]) constructor, and it should be used any time the content is available via a URL or a file. However, this class does provide the ability to convert bidirectionally between a byte array and InputStream no matter how it was originally instantiated. But beware that a conversion of a large File to a byte array could be expensive because of the memory footprint that the return value would occupy, so try to keep that use to a minimum or at least quickly discard all references to that byte array return value.

If you are an implementer of the dataAPI interface, you will be handed Blobs which were constructed with byte arrays. This is because AMP gets the DomainVersion blobs from the device via SOAP messages, so they haven't been persisted in a local file at that point. When you persist a DomainVersion blob to your repository, it is HIGHLY recommended that you first invoke hasBytes() to see if it was instantiated with a byte array or a File object. If it was instantiated with a byte array and your dataAPI implementation persists Blobs to a file, you should serialize the Blob contents to a file in your repository, create a new Blob instance using Blob(File) with the repository file you just created, and use that File-based Blob in the StoredDomainVersion object instead of the original byte-array-based Blob. Then discard references to the original Blob with the byte array. After garbage collection then the Blob with a byte array should no longer be in memory. If you fail to follow this method, then every DomainVersion blob will be in memory in their entirety. With regard to FirmwareVersion, hopefully the UI will create those Blobs via Blob(File) so you won't have this issue with that class, but verify that the UI is doing it that way by invoking hasBytes().


Field Summary
static java.lang.String COPYRIGHT_2009_2013
           
 
Constructor Summary
Blob(byte[] bytes)
          Create a new blob object from a byte array.
Blob(java.io.File file)
          Create a new blob object from a file.
Blob(java.net.URL url)
          Create a new blob object from a URL.
 
Method Summary
 boolean canRead()
          A check to verify that the content can be read when needed.
 Blob getBase64Encoded()
          Create a new Blob object for Base64-encode firmware images, so that they need to be encoded only once when initially added to the repository instead of on each setFirmware request.
 byte[] getByteArray()
          Get the contents of the blob as a byte array.
 java.lang.String getFilenameExtension()
          Return the filename extension of the file client given when creating this blob object.
 java.io.InputStream getInputStream()
          Get the contents of the blob as an InputStream.
 boolean hasBytes()
          Query the object to see if it already has its contents stored as a byte[].
 void toFile(java.lang.String filename)
          Write the contents of the Blob to a file.
 java.lang.String toString()
          Get a String representation of this Blob for the purpose of debugging or tracing.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

COPYRIGHT_2009_2013

public static final java.lang.String COPYRIGHT_2009_2013
See Also:
Constant Field Values
Constructor Detail

Blob

public Blob(java.net.URL url)
Create a new blob object from a URL.

Parameters:
url - a URL representing the location of the blob source The URL location is not read during the constructor, it is instead read by the consumer of getInputStream(), or read into memory if you call getByteArray(). So it is expected that this URL parameter should exist and be available for reading during the lifetime of this Blob object. If that is not possible, then you need to use the constructor Blob(byte[]). Supported URL schemes are file:, http:, and https:

Blob

public Blob(java.io.File file)
Create a new blob object from a file.

Parameters:
file - a reference to the file that contains the binary data. The File contents are not read during the constructor, but are read by the consumer of getInputStream(), or they are read into memory if you call getByteArray(). So it is expected that this File parameter should exist and be available for reading during the lifetime of this Blob object. If that is not possible, then you need to use the constructor Blob(byte[]).

Blob

public Blob(byte[] bytes)
Create a new blob object from a byte array. We recommend against using this, especially for the long term, because it means that the entire byte array will be resident in memory for the lifetime of this object. It is preferred that you use the Blob(File) constructor so that this object does not trigger large memory usage.

Parameters:
bytes - the byte array that contains the binary data. This class will reference this byte array and not copy it, so beware of making changes to your array after you use it as an argument for this constructor.
Method Detail

hasBytes

public boolean hasBytes()
Query the object to see if it already has its contents stored as a byte[]. Since doing a conversion from a File or Base64 to a byte[] could potentially be very expensive (depending on the size of the File or Base64), you may want to use this method to avoid invoking this conversion if you are concerned about consuming heap memory.

This method needs to be public so it can be invoked by the dataAPI.

Returns:
true if the Blob already has loaded a byte array, false if the Blob contents are stored in a file.

canRead

public boolean canRead()
A check to verify that the content can be read when needed.

Returns:
true if the content can be read, false otherwise. This is used mostly when a Blob was constructed from a File. This method checks to make sure the File exists and that the File is readable. If this Blob was constructed from a byte array it always returns true.

getByteArray

public byte[] getByteArray()
                    throws java.io.IOException
Get the contents of the blob as a byte array.

If the Blob was initially constructed via a byte array, it will just return a reference to that same byte array.

If the Blob was initially constructed via a File, it will open the file, allocate a byte array large enough to hold the contents, read the file into that byte array, and return a reference to the byte array. Doing that may be quite expensive if the file is large. This method does not cause this object to have a reference to the byte array, so as soon as the caller is done with the return value it may be eligible for garbage collection.

This method needs to be public so it can be invoked by the dataAPI.

Returns:
a byte array representation of the binary data

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException
Get the contents of the blob as an InputStream.

If the Blob was initially constructed via a File, this will open the file and return the InputStream pointing at the beginning of the file. It is up to the caller to close the InputStream.

If the Blob was initially constructed via a byte array, this will wrap the byte array with an InputStream. No file is actually created, and the byte array is not copied. For good measure, the caller should close the InputStream.

This method needs to be public so it can be invoked by the dataAPI.

Returns:
an InputStream representation of the binary data

getFilenameExtension

public java.lang.String getFilenameExtension()
Return the filename extension of the file client given when creating this blob object. If a byte array is used to create the blob the method will return null since there is no filename involved.

Returns:
a string of filename extension of the source file of the blob

getBase64Encoded

public Blob getBase64Encoded()
                      throws java.io.IOException
Create a new Blob object for Base64-encode firmware images, so that they need to be encoded only once when initially added to the repository instead of on each setFirmware request. This one-time encoding is a performance/resource optimization.

Be aware that the contents of the new Blob (return value) are stored in memory as a byte array rather than as a file. So you may want to persist the contents to disk ASAP and create another Blob using Blob(File) so that the contents are held on disk instead of in memory. Or you can make the return value eligible for garbage collection ASAP.

Returns:
a new Blob that is a Base64-encoded version of the existing Blob

toString

public java.lang.String toString()
Get a String representation of this Blob for the purpose of debugging or tracing.

Overrides:
toString in class java.lang.Object
Returns:
a String representation of this Blob for the purpose of debugging or tracing. Only metadata will be included, not the binary contents

toFile

public void toFile(java.lang.String filename)
            throws java.io.IOException
Write the contents of the Blob to a file. This will put it on disk independent of it having been constructed from a byte array or a file. This is used primarily for generating trace/debug data.

Parameters:
filename - the name of the file to create to hold the contents of the Blob.


© Copyright IBM Corp. 2006, 2010 All Rights Reserved.