|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.ibm.datapower.wamt.clientAPI.Blob
public class Blob
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 |
---|
public static final java.lang.String COPYRIGHT_2009_2013
Constructor Detail |
---|
public Blob(java.net.URL url)
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:public Blob(java.io.File file)
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[])
.public Blob(byte[] bytes)
Blob(File)
constructor so that this
object does not trigger large memory usage.
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 |
---|
public boolean hasBytes()
This method needs to be public so it can be invoked by the dataAPI.
public boolean canRead()
public byte[] getByteArray() throws java.io.IOException
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.
public java.io.InputStream getInputStream() throws java.io.IOException
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.
public java.lang.String getFilenameExtension()
public Blob getBase64Encoded() throws java.io.IOException
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.
public java.lang.String toString()
toString
in class java.lang.Object
public void toFile(java.lang.String filename) throws java.io.IOException
filename
- the name of the file to create to hold the contents of
the Blob.
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |