Blobs are a general-purpose interchange format. They can be passed into, and returned by, a variety of Gears methods. Blobs are, in many ways, parallel to Strings. Most APIs that accept a 'String' could be updated to accept 'String-or-Blob'.
Blobs are immutable. The binary data referenced by a Blob cannot be modified directly. (This guarantees Blobs will have predictable behavior when passed to asynchronous APIs.) In practice, this is not a limitation; APIs can accept Blobs and return new Blobs. Note that JavaScript strings are also immutable; they behave the same way.
Throwing exceptions
Any operation involving a Blob may throw an exception. This includes:
Exceptions can occur because Blobs may be backed by user files. If such a file changes, the Blob referencing it is no longer valid.
It is somewhat uncommon for files to change while they are being referenced. But web applications that want to be completely robust should handle this scenario.
Permission
The Blob API does not require user permission.
An SQL CLOB type stores a large array of bytes (binary data) as the value in a column of a database.
The java.sql.Blob interface provides methods for setting and retrieving data in the Blob, for querying Clob data length, for searching for data within the Blob.
Two blobs are considered equal in terms of {@link Object#equals(Object)}if they contain the same sequences of bytes. Implementations can optimize the equality checks by using strong hash codes or other similar means as long as they comply with the above definition of equality.
Due to their nature blobs should not be used as keys in hash tables. To highlight that and to ensure semantic correctness of the equality contract across different blob implementations, the {@link #hashCode()}method of all blob instances should return zero.
Storing and retrieving data to and from the blob happens through {@link java.io.OutputStream} and{@link java.io.InputStream}.
These streams are available via the Repository through {@link Repository#getOutputStream(Blob)} and{@link Repository#getInputStream(Blob)}.
Important: to add a blob to a record, you first need to upload the data via the OutputStream. Once finished, close the OutputStream using {@link java.io.OutputStream#close()}. This will trigger the update of the {@link #setValue value} of this blob object (which will usually be a pointer to the storage locationof the blob, though for tiny blobs -- sorry for the oxymoron -- this might be the binary data itself). Once that's done, you can store the {@link Record} itself. Thus: first upload all blobs and close theirOutputStreams, then save the record. It does not matter when the blob value is set on the record object itself.
This type is used to implement the primitive 'bytes' type of a protocol buffer in a manner that is more suitable for web-based DTOs based on JSON. The standard type, {@link com.google.protobuf.ByteString}, is not easily cross-compilable (e.g., by GWT), and does not have an obvious and efficient JSON serialization.
This type holds an encoding of arbitrary data as a string. The string encoding is unspecified, so the value of {@link #getData()} should not beinterpreted to be meaningful.
| |
| |
| |
| |
| |