contrib/phpcr/PHPCR/Value.php

<?php

/*
 * Copyright 2004-2005 The Apache Software Foundation or its licensors,
 *                     as applicable.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


require_once 'PHPCR/ValueFormatException.php';
require_once 'PHPCR/IllegalStateException.php';
require_once 'PHPCR/RepositoryException.php';


/**
 * A generic holder for the value of a property. A <code>Value</code> object can be used without knowing the actual
 * property type (<code>STRING</code>, <code>DOUBLE</code>, <code>BINARY</code> etc.).
 * <p>
 * Any implementation of this interface must match the behavior of the JCR-supplied classes ({@link BaseValue} and its
 * subclasses) in the following respects:
 * <ul>
 *   <li>
 *     A <code>Value</code> object returned by <code>Property.getValue()</code> can be read using type-specific
 *     <code>get</code> methods. These methods are divided into two groups:
 *     <ul>
 *       <li>
 *         The non-stream <code>get</code> methods <code>getString()</code>, <code>getDate()</code>,
 *         <code>getLong()</code>, <code>getDouble()</code> and <code>getBoolean()</code>.
 *       </li>
 *       <li>
 *          <code>getStream()</code>.
 *       </li>
 *     </ul>
 *    </li>
 *   <li>
 *     Once a <code>Value</code> object has been read once using <code>getStream()</code>, all subsequent calls to
 *     <code>getStream()</code> will return the same <code>Stream</code> object. This may mean, for example, that the
 *     stream returned is fully or partially consumed. In order to get a fresh stream the <code>Value</code> object
 *     must be reacquired via {@link Property#getValue()} or {@link Property#getValues()}.
 *   </li>
 *   <li>
 *     Once a <code>Value</code> object has been read once using <code>getStream()</code>, any subsequent call to any
 *     of the non-stream <code>get</code> methods will throw an <code>IllegalStateException</code>. In order to
 *     successfully invoke a non-stream <code>get</code> method, the <code>Value</code> must be reacquired.
 *   </li>
 *   <li>
 *     Once a <code>Value</code> object has been read once using a non-stream get method, any subsequent call to
 *     <code>getStream()</code> will throw an <code>IllegalStateException</code>. In order to successfully invoke
 *     <code>getStream()</code>, the <code>Value</code> must be reacquired.
 * </ul>
 * An implementation that obeys these restrictions can be found in the class {@link BaseValue} and its subclasses
 * {@link StringValue}, {@link LongValue}, {@link DoubleValue}, {@link BooleanValue}, {@link DateValue},
 * {@link BinaryValue}, {@link NameValue}, {@link PathValue} and {@link ReferenceValue}.
 * <p/>
 * Two <code>Value</code> instances, <code>v1</code> and <code>v2</code>, are considered equal if and only if:
 * <ul>
 * <li><code>v1.getType() == v2.getType()</code>, and,</li>
 * <li><code>v1.getString().equals(v2.getString())</code></li>
 * </ul>
 * Actually comparing two <code>Value</code> 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 <code>Value</code> 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.
 *
 * @author Markus Nix <mnix@mayflower.de>
 * @package phpcr
 */
interface Value
{
    /**
     * Returns a <code>String</code> representation of this value.
     * <p>
     * If this value cannot be converted to a string, a
     * <code>ValueFormatException</code> is thrown.
     * <p>
     * If <code>getStream</code> has previously been called on this
     * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
     * In this case a new <code>Value</code> instance must be acquired in order to
     * successfully call <code>getString</code>.
     * <p>
     * A <code>RepositoryException</code> is thrown if another error occurs.
     *
     * @return A <code>String</code> representation of the value of this property.
     * @throws ValueFormatException if conversion to a <code>String</code> is not possible.
     * @throws IllegalStateException if <code>getStream</code> has previously
     * been called on this <code>Value</code> instance.
     * @throws RepositoryException if another error occurs.
     */
    public function getString();

    /**
     * Returns an <code>InputStream</code> representation of this value.
     * USes the standard conversion to binary (see JCR specification)<p>
     * If this value cannot be converted to a stream, a
     * <code>ValueFormatException</code> is thrown.
     * <p>
     * If a non-stream <code>get</code> method has previously been called on this
     * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
     * In this case a new <code>Value</code> instance must be acquired in order to successfully call
     * <code>getStream</code>.
     * <p>
     * A <code>RepositoryException</code> is thrown if another error occurs.
     *
     * @return An <code>InputStream</code> representation of this value.
     * @throws ValueFormatException if conversion to an <code>InputStream</code> is not possible.
     * @throws IllegalStateException if a non-stream <code>get</code> method has previously
     * been called on this <code>Value</code> instance.
     * @throws RepositoryException if another error occurs.
     */
    public function getStream();

    /**
     * Returns a <code>long</code> representation of this value.
     * <p>
     * If this value cannot be converted to a <code>long</code>, a
     * <code>ValueFormatException</code> is thrown.
     * <p>
     * If <code>getStream</code> has previously been called on this
     * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
     * In this case a new <code>Value</code> instance must be acquired in order to
     * successfully call <code>getLong</code>.
     * <p>
     * A <code>RepositoryException</code> is thrown if another error occurs.
     *
     * @return A <code>long</code> representation of this value.
     * @throws ValueFormatException if conversion to a <code>long</code> is not possible.
     * @throws IllegalStateException if <code>getStream</code> has previously
     * been called on this <code>Value</code> instance.
     * @throws RepositoryException if another error occurs.
     */
    public function getLong();

    /**
     * Returns a <code>double</code> representation of this value.
     * <p>
     * If this value cannot be converted to a <code>double</code>, a
     * <code>ValueFormatException</code> is thrown.
     * <p>
     * If <code>getStream</code> has previously been called on this
     * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
     * In this case a new <code>Value</code> instance must be acquired in order to
     * successfully call <code>getDouble</code>.
     * <p>
     * A <code>RepositoryException</code> is thrown if another error occurs.
     *
     * @return A <code>double</code> representation of this value.
     * @throws ValueFormatException if conversion to a <code>double</code> is not possible.
     * @throws IllegalStateException if <code>getStream</code> has previously
     * been called on this <code>Value</code> instance.
     * @throws RepositoryException if another error occurs.
     */
    public function getDouble();

    /**
     * Returns date representation of this value.
     * <p>
     * If this value cannot be converted to a <code>Calendar</code>, a
     * <code>ValueFormatException</code> is thrown.
     * <p>
     * If <code>getStream</code> has previously been called on this
     * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
     * In this case a new <code>Value</code> instance must be acquired in order to
     * successfully call <code>getDate</code>.
     * <p>
     * A <code>RepositoryException</code> is thrown if another error occurs.
     *
     * @return date
     * @throws ValueFormatException if conversion to a <code>Calendar</code> is not possible.
     * @throws IllegalStateException if <code>getStream</code> has previously
     * been called on this <code>Value</code> instance.
     * @throws RepositoryException if another error occurs.
     */
    public function getDate();

    /**
     * Returns a <code>Boolean</code> representation of this value.
     * <p>
     * If this value cannot be converted to a <code>Boolean</code>, a
     * <code>ValueFormatException</code> is thrown.
     * <p>
     * If <code>getStream</code> has previously been called on this
     * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
     * In this case a new <code>Value</code> instance must be acquired in order to
     * successfully call <code>getBoolean</code>.
     * <p>
     * A <code>RepositoryException</code> is thrown if another error occurs.
     *
     * @return A <code>Boolean</code> representation of this value.
     * @throws ValueFormatException if conversion to a <code>Boolean</code> is not possible.
     * @throws IllegalStateException if <code>getStream</code> has previously
     * been called on this <code>Value</code> instance.
     * @throws RepositoryException if another error occurs.
     */
    public function getBoolean();

    /**
     * Returns the <code>type</code> of this <code>Value</code>.
     * One of:
     * <ul>
     * <li><code>PropertyType::STRING</code></li>
     * <li><code>PropertyType::DATE</code></li>
     * <li><code>PropertyType::BINARY</code></li>
     * <li><code>PropertyType::DOUBLE</code></li>
     * <li><code>PropertyType::LONG</code></li>
     * <li><code>PropertyType::BOOLEAN</code></li>
     * <li><code>PropertyType::NAME</code></li>
     * <li><code>PropertyType::PATH</code></li>
     * <li><code>PropertyType::REFERENCE</code></li>
     * </ul>
     * See <code>{@link PropertyType}</code>.
     * <p>
     * The type returned is that which was set at property creation.
     */
    public function getType();
}

?>