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