eu.fbk.knowledgestore.data

Class Representation

java.lang.Object

eu.fbk.knowledgestore.data.Representation

All Implemented Interfaces:

Closeable, AutoCloseable

public final class Representation
extends Object
implements Closeable

A digital representation of a resource.

A Representation object provides access to the binary or character representation of a resource, including associated (mutable) representation metadata (getMetadata()) and the resource ID ( #getResourceID()).

Representation data can be consumed either as a stream of bytes or as a stream of characters. Conversion from one stream to another is performed if necessary using the charset encoded by metadata attribute NIE.MIME_TYPE.

A representation encapsulates an open InputStream or Reader that provide access to the representation data (see methods getInputStream() and getReader()), hence it is a Closeable object that MUST be closed after use. In addition to these methods, a number of writeToXXX() helper methods allow to consume the representation data in different ways:

• writeToByteArray() returns a byte array with all the representation data;
• writeToString() returns a string with all the representation characater data.
• writeTo(OutputStream) writes all the binary representation data to a supplied OutputStream;
• writeTo(Appendable) writes the character representation data to a supplied Appendable;

Note that these methods exhaust the InputStream / Reader associated to the representation. Moreover, in case some data has already been read, it will not be written by those methods.

Representation objects are created via create() factory methods that take care of acquiring both an InputStream / Reader over the data and the associated metadata starting from a number of sources:

• #create(URI, InputStream) builds a representation out of an InputStream;
• #create(URI, Reader) builds a representation out of a Reader ;
• #create(URI, byte[]) builds a representation out of a byte array, including metadata about the representation length;
• #create(URI, CharSequence) builds a representation out of a CharSequence (e.g., a String);
• #create(URI, File) builds a representation out of a file, including metadata about the file name, size, mime type (from the extension) and last modified time;
• #create(URI, URL) builds a representation out of a resolvable URL, including metadata about the file name, file size, mime type (from the extension), MD5 hash, last modified time.

Representation objects are mutable but thread safe. Object equality is used for equals() and hashCode().

Method Summary

Modifier and Type	Method and Description
void	close()
static Representation	create(byte[] bytes) Creates a representation based on the byte array specified.
static Representation	create(CharSequence sequence) Creates a representation based on the CharSequence specified.
static Representation	create(File file, boolean autoDecompress) Creates a representation based on the File specified.
static Representation	create(InputStream stream) Creates a representation based on the InputStream specified.
static Representation	create(Reader reader) Creates a representation based on the Reader specified.
static Representation	create(URL url) Creates a representation based on the resolvable URL specified.
protected void	finalize()
InputStream	getInputStream() Returns an InputStream over the binary data of this representation object.
Record	getMetadata() Returns the metadata about this representation.
Reader	getReader() Returns a Reader over the character data of this representation object.
String	toString() The returned representation contains the associated resource ID.
void	writeTo(Appendable sink) Writes all the character data of this representation to the Appendable sink specified.
void	writeTo(OutputStream sink) Writes all the binary data of this representation to the OutputStream sink specified.
byte[]	writeToByteArray() Writes all the binary data of this representation to a byte[] object.
String	writeToString() Writes all the character data of this representation to a String object.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

create

public static Representation create(InputStream stream)

Creates a representation based on the InputStream specified. Note that the supplied InputStream is never closed by this class: it MUST be closed externally under the responsibility of the caller.

Parameters:

stream - the InputStream, not null

Returns:

the created representation

create

public static Representation create(byte[] bytes)

Creates a representation based on the byte array specified. The length of the byte array will be reflected in the returned representation metadata (property NFO.FILE_SIZE). Note that the byte array should not be changed after calling this method, as modification could be (partially) reflected in the returned representation.

Parameters:

bytes - the byte array containing the binary data of the representation

Returns:

the created representation

create

public static Representation create(File file,
                                    boolean autoDecompress)
                             throws IllegalArgumentException

Creates a representation based on the File specified. The file length, size, creation time and MIME type will be reflected in the returned representation metadata (respectively, properties NFO.FILE_SIZE, NFO.FILE_NAME, NFO.FILE_LAST_MODIFIED, NIE.MIME_TYPE). Note that this method causes the file to be opened for reading.

Parameters:

file - the file containing the binary data of the representation

autoDecompress - automatically decompress the file, if compressed with gzip, bzip2, xz, 7z or lz4

Returns:

the created representation

Throws:

IllegalArgumentException - in case the file does not exist

create

public static Representation create(URL url)
                             throws IllegalArgumentException

Creates a representation based on the resolvable URL specified. This method has the effect of acquiring a connection to the supplied URL, from which the representation stream and a number of metadata attributes are extracted. These attributes include the last modified timestamp (NFO.FILE_LAST_MODIFIED), the MIME type (NIE.MIME_TYPE), the file size (NFO.FILE_SIZE), the file name (NFO.FILE_NAME) and the MD5 hash ( NFO.HAS_HASH); all of these attributes are optional and are extracted only if available.

Parameters:

url - the URL that, resolved, will produced the binary data of the representation

Returns:

the created representation

Throws:

IllegalArgumentException - in case acquiring a connection to the supplied URL fails

create

public static Representation create(Reader reader)

Creates a representation based on the Reader specified. Note that the supplied Reader is never closed by this class: it MUST be closed externally under the responsibility of the caller. Upon request (e.g., invocation of getInputStream()), character data produced by the Reader will be translated into byte data either using the charset specified in the representation metadata (property NIE.MIME_TYPE) or by using UTF-8.

Parameters:

reader - the reader producing the character data of the representation

Returns:

the created representation

create

public static Representation create(CharSequence sequence)

Creates a representation based on the CharSequence specified. Upon request (e.g., invocation of getInputStream()), character data produced by the Reader will be translated into byte data either using the charset specified in the representation metadata (property NIE.MIME_TYPE) or by using UTF-8.

Parameters:

sequence - the CharSequence with the character data of the representation

Returns:

the created representation

getMetadata

public Record getMetadata()

Returns the metadata about this representation.

Returns:

the representation metadata, not null

getInputStream

public InputStream getInputStream()

Returns an InputStream over the binary data of this representation object. Conversion from character to byte data, if required, is performed according to the charset specified by the MIME type metadata property (NIE.MIME_TYPE).

Returns:

an InputStream over the binary content of this representation

getReader

public Reader getReader()

Returns a Reader over the character data of this representation object. Conversion from byte to character data, if required, is performed according to the charset specified by the MIME type metadata property (NIE.MIME_TYPE).

Returns:

a Reader providing access to the character data of the representation.

writeToByteArray

public byte[] writeToByteArray()
                        throws IOException

Writes all the binary data of this representation to a byte[] object. Conversion from character to byte data, if required, is performed according to the charset specified by the MIME type metadata property (NIE.MIME_TYPE). If some data has been already read via getInputStream() or getReaer(), it will not be returned in the result.

Returns:

a byte array with the binary content of this representation

Throws:

IOException - in case access to binary data fails

writeToString

public String writeToString()
                     throws IOException

Writes all the character data of this representation to a String object. Conversion from byte to character data, if required, is performed according to the charset specified by the MIME type metadata property (NIE.MIME_TYPE). If some data has been already read via getInputStream() or getReaer(), it will not be returned in the result.

Returns:

a String containg the full character-based content of this representation

Throws:

IOException - in case access to binary data fails

writeTo

public void writeTo(OutputStream sink)
             throws IOException

Writes all the binary data of this representation to the OutputStream sink specified. Conversion from character to byte data, if required, is performed according to the charset specified by the MIME type metadata property (NIE.MIME_TYPE). If some data has been already read via getInputStream() or getReaer(), it will not be written to the supplied sink.

Parameters:

sink - the sink where to write binary data to

Throws:

IOException - in case access to binary data fails

writeTo

public void writeTo(Appendable sink)
             throws IOException

Writes all the character data of this representation to the Appendable sink specified. Conversion from byte to character data, if required, is performed according to the charset specified by the MIME type metadata property (NIE.MIME_TYPE). If some data has been already read via getInputStream() or getReaer(), it will not be written to the supplied sink.

Parameters:

sink - the sink where to write character data to

Throws:

IOException - in case access to binary data fails

close

public void close()

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

toString

public String toString()

The returned representation contains the associated resource ID.

Overrides:

toString in class Object