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


Copyright © 2008-2009 JBoss, a division of Red Hat. All Rights Reserved.