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}