001/*
002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Nuxeo - initial API and implementation
011 *
012 * $Id$
013 */
014
015package org.nuxeo.ecm.core.api;
016
017import java.io.Serializable;
018import java.util.Collection;
019import java.util.Map;
020
021import org.nuxeo.ecm.core.api.model.PropertyNotFoundException;
022
023/**
024 * A data model is a concrete representation of a schema.
025 * <p>
026 * The schema describe the data structure and the data model object is storing concrete values according to that
027 * structure.
028 * <p>
029 * When the user modifies a data structure the modified fields are tracked so that at any time you can query about the
030 * dirty state of the data model by using the {@link DataModel#isDirty()} and {@link DataModel#isDirty(String)} methods.
031 * <p>
032 * The data model can be modified only through the set methods:
033 * <ul>
034 * <li> {@link DataModel#setData(String, Object)}
035 * <li> {@link DataModel#setMap(Map)}
036 * </ul>
037 * This is ensuring the dirty state will be correctly updated
038 * <p>
039 * This is the reason why the {@link DataModel#getMap()} method is returning a read only map.
040 * <p>
041 * Data structure are usually part of a composite model as the {@link DocumentModel}.
042 *
043 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
044 */
045public interface DataModel extends Serializable {
046
047    /**
048     * Gets the schema of this data model.
049     *
050     * @return the data model schema
051     */
052    String getSchema();
053
054    /**
055     * Sets the name field.
056     *
057     * @param key the field name
058     * @param value the value to set. Accept null values.
059     * @throws PropertyException
060     */
061    void setData(String key, Object value) throws PropertyException;
062
063    /**
064     * Gets the named field value.
065     *
066     * @param key the field key
067     * @return the value or null if no such field exists
068     * @throws PropertyException
069     */
070    Object getData(String key) throws PropertyException;
071
072    /**
073     * Gets all the fields set in this data model.
074     * <p>
075     * It is not guaranteed that the returned map will contain all the fields defined by the schema. It may even be
076     * empty.
077     * <p>
078     * The returned map is null if the data model was not yet loaded.
079     *
080     * @return a read only map containing actual data in this object
081     * @throws PropertyException
082     */
083    Map<String, Object> getMap() throws PropertyException;
084
085    /**
086     * Sets several field at once.
087     *
088     * @param data the fields to set as a map
089     * @throws PropertyException
090     */
091    void setMap(Map<String, Object> data) throws PropertyException;
092
093    /**
094     * Tests whether or not this data model is dirty (i.e. it was changed by the client).
095     *
096     * @return true if the data model is dirty, false otherwise
097     */
098    boolean isDirty();
099
100    /**
101     * Tests whether or not the specified field from this data model is dirty.
102     *
103     * @param name the field name to tests
104     * @return true if the field is dirty, false otherwise
105     * @throws PropertyNotFoundException
106     */
107    boolean isDirty(String name) throws PropertyNotFoundException;
108
109    /**
110     * Marks the specified field from this data model as dirty.
111     *
112     * @param name the field name to be dirty
113     * @throws PropertyNotFoundException
114     */
115    void setDirty(String name) throws PropertyNotFoundException;
116
117    /**
118     * Gets the collection of the dirty fields in this data model.
119     *
120     * @return the dirty fields or null if there are no dirty fields
121     */
122    Collection<String> getDirtyFields();
123
124    /**
125     * Gets a value given its path.
126     * <p>
127     * The path is a subset of XPath: / and [] are supported.
128     *
129     * @param path the property path
130     * @return
131     * @throws PropertyException
132     */
133    Object getValue(String path) throws PropertyException;
134
135    /**
136     * Sets a value to a property given its path.
137     *
138     * @param path
139     * @param value
140     * @return
141     * @throws PropertyException
142     */
143    Object setValue(String path, Object value) throws PropertyException;
144
145}