DataObject


1   /* ====================================================================
2    * 
3    * The ObjectStyle Group Software License, version 1.1
4    * ObjectStyle Group - http://objectstyle.org/
5    * 
6    * Copyright (c) 2002-2005, Andrei (Andrus) Adamchik and individual authors
7    * of the software. All rights reserved.
8    * 
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   * 
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   * 
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   * 
21   * 3. The end-user documentation included with the redistribution, if any,
22   *    must include the following acknowlegement:
23   *    "This product includes software developed by independent contributors
24   *    and hosted on ObjectStyle Group web site (http://objectstyle.org/)."
25   *    Alternately, this acknowlegement may appear in the software itself,
26   *    if and wherever such third-party acknowlegements normally appear.
27   * 
28   * 4. The names "ObjectStyle Group" and "Cayenne" must not be used to endorse
29   *    or promote products derived from this software without prior written
30   *    permission. For written permission, email
31   *    "andrus at objectstyle dot org".
32   * 
33   * 5. Products derived from this software may not be called "ObjectStyle"
34   *    or "Cayenne", nor may "ObjectStyle" or "Cayenne" appear in their
35   *    names without prior written permission.
36   * 
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE OBJECTSTYLE GROUP OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   * 
51   * This software consists of voluntary contributions made by many
52   * individuals and hosted on ObjectStyle Group web site.  For more
53   * information on the ObjectStyle Group, please see
54   * <http://objectstyle.org/>.
55   */
56  package org.objectstyle.cayenne;
57  
58  import org.objectstyle.cayenne.access.DataContext;
59  import org.objectstyle.cayenne.validation.ValidationResult;
60  
61  /** 
62   * Defines basic methods for a persistent object in Cayenne.
63   * 
64   * @author Andrei Adamchik
65   */
66  public interface DataObject extends Persistent {
67      public static final long DEFAULT_VERSION = Long.MIN_VALUE;
68  
69      ObjectId getObjectId();
70  
71      void setObjectId(ObjectId id);
72      
73      /** 
74       * Returns a data context this object is registered with, or null
75       * if this object has no associated DataContext.
76       */
77      public DataContext getDataContext();
78  
79      /** 
80       * Sets object DataContext. 
81       */
82      public void setDataContext(DataContext ctxt);
83  
84      /** 
85       * Modifies a value of a named property without altering the object state in any way,
86       * and without triggering any database operations. This method is intended mostly for internal
87       * use by Cayenne framework, and shouldn't be called from the application code. 
88       */
89      public void writePropertyDirectly(String   propertyName, Object   val);
90  
91      /** 
92       * Returns mapped property value as curently stored in the DataObject.
93       * Returned value maybe a fault or a real value. This method will not attempt 
94       * to resolve faults, or to read unmapped properties.
95       */
96      public Object   readPropertyDirectly(String   propertyName);
97  
98      /**
99       * Returns a value of the property identified by a property path. Supports reading both
100      * mapped and unmapped properties. Unmapped properties are accessed in a manner consistent 
101      * with JavaBeans specification.
102      * 
103      * <p>
104      * Property path (or nested property) is a 
105      * dot-separated path used to traverse object relationships until the final object 
106      * is found. If a null object found while traversing path, null is returned. If a 
107      * list is encountered in the middle of the path, CayenneRuntimeException is thrown.
108      * Unlike {@link #readPropertyDirectly(String)}, this method will resolve an object
109      * if it is HOLLOW.
110      *
111      * <p>Examples:</p>
112      * <ul>
113      *    <li>Read this object property:<br>
114      *    <code>String name = (String)artist.readNestedProperty("name");</code><br><br></li>
115      *
116      *    <li>Read an object related to this object:<br>
117      *    <code>Gallery g = (Gallery)paintingInfo.readNestedProperty("toPainting.toGallery");</code>
118      *    <br><br></li>
119      *
120      *    <li>Read a property of an object related to this object: <br>
121      *    <code>String name = (String)painting.readNestedProperty("toArtist.artistName");</code>
122      *    <br><br></li>
123      *
124      *    <li>Read to-many relationship list:<br>
125      *    <code>List exhibits = (List)painting.readNestedProperty("toGallery.exhibitArray");</code>
126      *    <br><br></li>
127      *
128      *    <li>Read to-many relationship in the middle of the path <b>(throws exception)</b>:<br>
129      *    <code>String name = (String)artist.readNestedProperty("paintingArray.paintingName");</code>
130      *   <br><br></li>
131      * </ul>
132      * 
133      * @since 1.0.5
134      *
135      */
136     public Object   readNestedProperty(String   path);
137     
138     /**
139     * Returns a value of the property identified by propName. Resolves faults if needed.
140     * This method can safely be used instead of or in addition to the auto-generated property
141     * accessors in subclasses of CayenneDataObject.
142     */
143     public Object   readProperty(String   propName);
144 
145     /**
146     * Sets the property with the name propName to the new value val. Resolves faults if needed
147     * This method can safely be used instead of or in addition to the auto-generated property
148     * modifiers in subclasses of CayenneDataObject.
149     */
150     public void writeProperty(String   propName, Object   val);
151 
152     public void addToManyTarget(String   relName, DataObject val, boolean setReverse);
153 
154     public void removeToManyTarget(String   relName, DataObject val, boolean setReverse);
155 
156     public void setToOneTarget(String   relName, DataObject val, boolean setReverse);
157 
158     /**
159      * Notification method called by DataContext after the object 
160      * was read from the database.
161      */
162     public void fetchFinished();
163 
164     /**
165      * Returns a version of a DataRow snapshot that was used to 
166      * create this object.
167      * 
168      * @since 1.1
169      */
170     public long getSnapshotVersion();
171 
172     /**
173      * @since 1.1
174      */
175     public void setSnapshotVersion(long snapshotVersion);
176 
177     /**
178      * Initializes object with data from cache or from the database,
179      * if this object is not fully resolved.
180      * 
181      * @since 1.1
182      */
183     public void resolveFault();
184 
185     /**
186      * Performs property validation of the NEW object, appending any validation failures
187      * to the provided validationResult object. This method is invoked by DataContext
188      * before committing a NEW object to the database.
189      * 
190      * @since 1.1
191      */
192     public void validateForInsert(ValidationResult validationResult);
193 
194     /**
195      * Performs property validation of the MODIFIED object, appending any validation failures
196      * to the provided validationResult object. This method is invoked by DataContext
197      * before committing a MODIFIED object to the database.
198      * 
199      * @since 1.1
200      */
201     public void validateForUpdate(ValidationResult validationResult);
202 
203     /**
204      * Performs property validation of the DELETED object, appending any validation failures
205      * to the provided validationResult object. This method is invoked by DataContext
206      * before committing a DELETED object to the database.
207      * 
208      * @since 1.1
209      */
210     public void validateForDelete(ValidationResult validationResult);
211 }
212
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags