javax.jcr.Value 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
There is a newer version: 2024.9.17689.20240905T073330Z-240800
/*
 * Copyright 2009 Day Management AG, Switzerland. All rights reserved.
 */
package javax.jcr;

import java.io.InputStream;
import java.math.BigDecimal;
import java.util.Calendar;

/**
 * A generic holder for the value of a property. A Value object can
 * be used without knowing the actual property type (STRING,
 * DOUBLE, BINARY etc.).
 * 
 * The Binary interface and its related methods in
 * Property, Value and ValueFactory
 * replace the deprecated Value.getStream and
 * Property.getStream methods from JCR 1.0. However, though
 * getStream has been deprecated, for reasons of backward
 * compatibility its behavior must still conform to the following rules: 

 *  A Value object can be read using type-specific
 * get methods. These methods are divided into two groups: 
 *  The non-stream get methods getString(),
 * getBinary(), getDate(), getDecimal(),
 * getLong(), getDouble() and
 * getBoolean(). 
  getStream(). 
 
 * 
  Once a Value object has been read once using
 * getStream(), all subsequent calls to getStream()
 * will return the same Stream object. This may mean, for example,
 * that the stream returned is fully or partially consumed. In order to get a
 * fresh stream the Value object must be reacquired via {@link
 * Property#getValue()} or {@link Property#getValues()}. 
  Once a
 * Value object has been read once using getStream(),
 * any subsequent call to any of the non-stream get methods will
 * throw an IllegalStateException. In order to successfully invoke
 * a non-stream get method, the Value must be
 * reacquired via {@link Property#getValue()} or {@link Property#getValues()}.
 * 
  Once a Value object has been read once using a
 * non-stream get method, any subsequent call to getStream() will
 * throw an IllegalStateException. In order to successfully invoke
 * getStream(), the Value must be reacquired via
 * {@link Property#getValue()} or {@link Property#getValues()}. 
 * 
 * Two Value instances, v1 and v2, are
 * considered equal if and only if: 
 v1.getType() ==
 * v2.getType(), and,
 v1.getString().equals(v2.getString())
 * 
 Actually comparing two Value instances by converting them
 * to string form may not be practical in some cases (for example, if the values
 * are very large binaries). Consequently, the above is intended as a normative
 * definition of Value equality but not as a procedural test of
 * equality. It is assumed that implementations will have efficient means of
 * determining equality that conform with the above definition.
 * 
 * An implementation is only required to support equality comparisons on
 * Value instances that were acquired from the same
 * Session and whose contents have not been read. The equality
 * comparison must not change the state of the Value instances even
 * though the getString() method in the above definition implies a
 * state change.
 */
public interface Value {

    /**
     * Returns a String representation of this value.
     *
     * @return A String representation of the value of this
     *         property.
     * @throws ValueFormatException  if conversion to a String is
     *                               not possible.
     * @throws IllegalStateException if getStream has previously
     *                               been called on this Value instance. In this case a new
     *                               Value instance must be acquired in order to successfully
     *                               call this method.
     * @throws RepositoryException   if another error occurs.
     */
    public String getString() throws ValueFormatException, IllegalStateException, RepositoryException;

    /**
     * Returns an InputStream representation of this value. Uses
     * the standard conversion to binary (see JCR specification).
     * 

     * It is the responsibility of the caller to close the returned
     * InputStream.
     *
     * @return An InputStream representation of this value.
     * @throws RepositoryException if an error occurs.
     * @deprecated As of JCR 2.0, {@link #getBinary()} should be used instead.
     */
    public InputStream getStream() throws RepositoryException;

    /**
     * Returns a Binary representation of this value. The {@link
     * Binary} object in turn provides methods to access the binary data itself.
     * Uses the standard conversion to binary (see JCR specification).
     *
     * @return A Binary representation of this value.
     * @throws RepositoryException if an error occurs.
     * @since JCR 2.0
     */
    public Binary getBinary() throws RepositoryException;

    /**
     * Returns a long representation of this value.
     *
     * @return A long representation of this value.
     * @throws ValueFormatException if conversion to an long is not
     *                              possible.
     * @throws RepositoryException  if another error occurs.
     */
    public long getLong() throws ValueFormatException, RepositoryException;

    /**
     * Returns a double representation of this value.
     *
     * @return A double representation of this value.
     * @throws ValueFormatException if conversion to a double is
     *                              not possible.
     * @throws RepositoryException  if another error occurs.
     */
    public double getDouble() throws ValueFormatException, RepositoryException;

    /**
     * Returns a BigDecimal representation of this value.
     *
     * @return A BigDecimal representation of this value.
     * @throws ValueFormatException if conversion to a BigDecimal
     *                              is not possible.
     * @throws RepositoryException  if another error occurs.
     * @since JCR 2.0
     */
    public BigDecimal getDecimal() throws ValueFormatException, RepositoryException;

    /**
     * Returns a Calendar representation of this value.
     * 

     * The object returned is a copy of the stored value, so changes to it are
     * not reflected in internal storage.
     *
     * @return A Calendar representation of this value.
     * @throws ValueFormatException if conversion to a Calendar is
     *                              not possible.
     * @throws RepositoryException  if another error occurs.
     */
    public Calendar getDate() throws ValueFormatException, RepositoryException;

    /**
     * Returns a Boolean representation of this value.
     *
     * @return A Boolean representation of this value.
     * @throws ValueFormatException if conversion to a Boolean is
     *                              not possible.
     * @throws RepositoryException  if another error occurs.
     */
    public boolean getBoolean() throws ValueFormatException, RepositoryException;

    /**
     * Returns the type of this Value. One of: 

     * PropertyType.STRING
 PropertyType.DATE
     * PropertyType.BINARY
 PropertyType.DOUBLE
     * PropertyType.DECIMAL
     * PropertyType.LONG
 PropertyType.BOOLEAN
     * PropertyType.NAME
 PropertyType.PATH
     * PropertyType.REFERENCE
 PropertyType.WEAKREFERENCE
     * PropertyType.URI
 See {@link
     * PropertyType}.
     * 
     * The type returned is that which was set at property creation.
     *
     * @return an int
     */
    public int getType();
}