javax.jcr.Binary Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of aem-sdk-api Show documentation
The Adobe Experience Manager SDK
The newest version!
/*
 * Copyright 2009 Day Management AG, Switzerland. All rights reserved.
 */
package javax.jcr;

import java.io.InputStream;
import java.io.IOException;

/**
 * A Binary object holds a JCR property value of type
 * BINARY. The Binary interface and the related
 * methods in {@link Property}, {@link Value} and {@link ValueFactory} replace
 * the deprecated {@link Value#getStream} and {@link Property#getStream}
 * methods.
 *
 * @since JCR 2.0
 */
public interface Binary {

    /**
     * Returns an {@link InputStream} representation of this value. Each call to
     * getStream() returns a new stream. The API consumer is
     * responsible for calling close() on the returned stream.
     * 
     * If {@link #dispose()} has been called on this Binary
     * object, then this method will throw the runtime exception
     * {@link java.lang.IllegalStateException}.
     *
     * @return A stream representation of this value.
     * @throws RepositoryException if an error occurs.
     */
    InputStream getStream() throws RepositoryException;

    /**
     * Reads successive bytes from the specified position in this
     * Binary into the passed byte array until either the byte
     * array is full or the end of the Binary is encountered.
     * 

     * If {@link #dispose()} has been called on this Binary
     * object, then this method will throw the runtime exception
     * {@link java.lang.IllegalStateException}.
     *
     * @param b        the buffer into which the data is read.
     * @param position the position in this Binary from which to start reading
     *                 bytes.
     * @return the number of bytes read into the buffer, or -1 if there is no
     *         more data because the end of the Binary has been reached.
     * @throws IOException              if an I/O error occurs.
     * @throws NullPointerException     if b is null.
     * @throws IllegalArgumentException if offset is negative.
     * @throws RepositoryException      if another error occurs.
     */
    int read(byte[] b, long position) throws IOException, RepositoryException;

    /**
     * Returns the size of this Binary value in bytes.
     * 
     * If {@link #dispose()} has been called on this Binary
     * object, then this method will throw the runtime exception
     * {@link java.lang.IllegalStateException}.
     *
     * @return the size of this value in bytes.
     * @throws RepositoryException if an error occurs.
     */
    long getSize() throws RepositoryException;

    /**
     * Releases all resources associated with this Binary object
     * and informs the repository that these resources may now be reclaimed.
     * An application should call this method when it is finished with the
     * Binary object.
     */
    void dispose();
}