Property.java

/*
 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
 *
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     Nuxeo - initial API and implementation
 *
 * $Id$
 */

package org.eclipse.ecr.core.model;

import java.util.Collection;
import java.util.Iterator;

import org.eclipse.ecr.core.api.DocumentException;
import org.eclipse.ecr.core.schema.types.Type;

/**
 * This class describes a document property.
 * <p>
 * Properties are lazily created.
 * This means a property can be retrieved
 * - using <code>getProperty(name)</code>) on the container -
 * even if it not already exists but was defined by the container schema.
 * <p>
 * The first time a write operation is invoked on such a property,
 * the property will be created by the underlying storage.
 *
 * @author  <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
 */
public interface Property {

    /**
     * Gets the name used to identify this property by its container.
     * <p>
     * If the container of this property is not supporting accessing properties by
     * names, returns the empty string.
     *
     * @return the object name or the empty string if the object has no name
     * @throws DocumentException if the type cannot be resolved
     */
    String getName() throws DocumentException;

    /**
     * Gets the property type.
     *
     * @return the property type
     */
    Type getType();

    /**
     * Gets the value of this property.
     *
     * @return this property's value
     * @throws DocumentException
     */
    Object getValue() throws DocumentException;

    /**
     * Sets the value of this property.
     *
     * @param value the value to set
     * @throws DocumentException
     */
    void setValue(Object value) throws DocumentException;

    /**
     * Tests whether or not this property is null.
     * <p>
     * A null property means that it is defined by the container schema
     * but was not yet set (so it may not exists as a persistent object)
     * <p>
     * If the property is null the first time a write operation is done
     * on it the property will be created by the underlying storage
     *
     * @return true if the property is null, false otherwise
     */
    boolean isNull();

    /**
     * Nullify this property.
     * <p>
     * The property is set to null which may result in being removed from the storage
     * (this aspect depends on the implementation)
     *
     * @throws DocumentException
     */
    void setNull() throws DocumentException;

    /**
     * Checks whether this property has child property with the given name.
     *
     * @return true if this property has children properties, false otherwise
     * @throws DocumentException
     * @throws UnsupportedOperationException if this is not a composite property
     */
    boolean isPropertySet(String name) throws DocumentException;

    /**
     * Gets the children property given its name.
     *
     * @param name the property name
     * @return the property
     * @throws DocumentException
     * @throws UnsupportedOperationException if this is not a composite property
     */
    Property getProperty(String name) throws DocumentException;

    /**
     * Gets the collection of the children properties.
     *
     * @return an iterator over the children properties
     * @throws DocumentException
     * @throws UnsupportedOperationException if this is not a composite property
     */
    Collection<Property> getProperties() throws DocumentException;

    /**
     * Gets an iterator over the children properties.
     *
     * @return an iterator over the children properties
     * @throws DocumentException
     * @throws UnsupportedOperationException if this is not a composite property
     */
    Iterator<Property> getPropertyIterator() throws DocumentException;

}