org.jboss.dna.graph.property
Interface BinaryFactory

All Superinterfaces:

ValueFactory<Binary>

All Known Implementing Classes:

AbstractBinaryValueFactory, InMemoryBinaryValueFactory

@ThreadSafe
public interface BinaryFactory
extends ValueFactory<Binary>

A factory for creating Binary instances. This interface extends the ValueFactory generic interface and adds specific methods for creating binary objects.

Field Summary

Fields inherited from interface org.jboss.dna.graph.property.ValueFactory

DEFAULT_DECODER, DEFAULT_ENCODER

Method Summary

Binary	create(File file) Create a binary value from the given file.
Binary	create(InputStream stream, long approximateLength, byte[] secureHash) Create a value from the binary content given by the supplied stream, the approximate length, and the SHA-1 secure hash of the content.
Binary	create(Reader reader, long approximateLength, byte[] secureHash) Create a value from the binary content given by the supplied reader, the approximate length, and the SHA-1 secure hash of the content.
Binary	find(byte[] secureHash) Find an existing binary value given the supplied secure hash.

Methods inherited from interface org.jboss.dna.graph.property.ValueFactory

create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, create, getPropertyType

Method Detail

create

Binary create(InputStream stream,
              long approximateLength,
              byte[] secureHash)
              throws ValueFormatException,
                     IoException

Create a value from the binary content given by the supplied stream, the approximate length, and the SHA-1 secure hash of the content. If the secure hash is null, then a secure hash is computed from the content. If the secure hash is not null, it is assumed to be the hash for the content and may not be checked.

Parameters:

stream - the stream containing the content to be used to create the value

approximateLength - the approximate length of the content (in bytes)

secureHash - the secure hash of the content in the stream; if null, the secure hash is computed from the content, and if not null it is assumed to be the correct secure hash (and is not checked)

Returns:

the value, or null if the supplied stream is null

Throws:

ValueFormatException - if the conversion from an input stream could not be performed

IoException - If an unexpected problem occurs while accessing the supplied stream (such as an IOException).

IllegalArgumentException - if the secure hash was discovered to be incorrect

create

Binary create(Reader reader,
              long approximateLength,
              byte[] secureHash)
              throws ValueFormatException,
                     IoException

Create a value from the binary content given by the supplied reader, the approximate length, and the SHA-1 secure hash of the content. If the secure hash is null, then a secure hash is computed from the content. If the secure hash is not null, it is assumed to be the hash for the content and may not be checked.

Parameters:

reader - the reader containing the content to be used to create the value

approximateLength - the approximate length of the content (in bytes)

secureHash - the secure hash of the content in the stream; if null, the secure hash is computed from the content, and if not null it is assumed to be the correct secure hash (and is not checked)

Returns:

the value, or null if the supplied string is null

Throws:

ValueFormatException - if the conversion from a reader could not be performed

IoException - If an unexpected problem occurs while accessing the supplied reader (such as an IOException).

IllegalArgumentException - if the secure hash was discovered to be incorrect

create

Binary create(File file)
              throws ValueFormatException,
                     IoException

Create a binary value from the given file.

Parameters:

file - the file containing the content to be used

Returns:

the binary value, or null if the file parameter was null

Throws:

ValueFormatException - if the conversion from the file could not be performed

IoException - If an unexpected problem occurs while accessing the supplied file (such as an IOException).

find

Binary find(byte[] secureHash)

Find an existing binary value given the supplied secure hash. If no such binary value exists, null is returned. This method can be used when the caller knows the secure hash (e.g., from a previously-held Binary object), and would like to reuse an existing binary value (if possible) rather than recreate the binary value by processing the stream contents. This is especially true when the size of the binary is quite large.

Parameters:

secureHash - the secure hash of the binary content, which was probably obtained from a previously-held Binary object; a null or empty value is allowed, but will always result in returning null

Returns:

the existing Binary value that has the same secure hash, or null if there is no such value available at this time