DataObject


1   /*****************************************************************
2    *   Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  You may obtain a copy of the License at
9    *
10   *    http://www.apache.org/licenses/LICENSE-2.0
11   *
12   *  Unless required by applicable law or agreed to in writing,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License.
18   ****************************************************************/
19  
20  package org.apache.cayenne;
21  
22  import org.apache.cayenne.access.DataContext;
23  
24  /**
25   * Defines basic methods for a persistent object in Cayenne.
26   * 
27   * @author Andrus Adamchik
28   */
29  public interface DataObject extends Persistent {
30  
31      public static final long DEFAULT_VERSION = Long.MIN_VALUE;
32  
33      /**
34       * Returns a data context this object is registered with, or null if this object has
35       * no associated DataContext.
36       * 
37       * @deprecated since 3.0 use {@link #getObjectContext()}.
38       */
39      public DataContext getDataContext();
40  
41      /**
42       * Sets object DataContext.
43       * 
44       * @deprecated since 3.0 use {@link #setObjectContext(ObjectContext)}.
45       */
46      public void setDataContext(DataContext ctxt);
47  
48      /**
49       * Modifies a value of a named property without altering the object state in any way,
50       * and without triggering any database operations. This method is intended mostly for
51       * internal use by Cayenne framework, and shouldn't be called from the application
52       * code.
53       */
54      public void writePropertyDirectly(String   propertyName, Object   val);
55  
56      /**
57       * Returns mapped property value as curently stored in the DataObject. Returned value
58       * maybe a fault or a real value. This method will not attempt to resolve faults, or
59       * to read unmapped properties.
60       */
61      public Object   readPropertyDirectly(String   propertyName);
62  
63      /**
64       * Returns a value of the property identified by a property path. Supports reading
65       * both mapped and unmapped properties. Unmapped properties are accessed in a manner
66       * consistent with JavaBeans specification.
67       * <p>
68       * Property path (or nested property) is a dot-separated path used to traverse object
69       * relationships until the final object is found. If a null object found while
70       * traversing path, null is returned. If a list is encountered in the middle of the
71       * path, CayenneRuntimeException is thrown. Unlike
72       * {@link #readPropertyDirectly(String)}, this method will resolve an object if it is
73       * HOLLOW.
74       * <p>
75       * Examples:
76       * </p>
77       * <ul>
78       * <li>Read this object property:<br>
79       * <code>String name = (String)artist.readNestedProperty("name");</code><br>
80       * <br>
81       * </li>
82       * <li>Read an object related to this object:<br>
83       * <code>Gallery g = (Gallery)paintingInfo.readNestedProperty("toPainting.toGallery");</code>
84       * <br>
85       * <br>
86       * </li>
87       * <li>Read a property of an object related to this object: <br>
88       * <code>String name = (String)painting.readNestedProperty("toArtist.artistName");</code>
89       * <br>
90       * <br>
91       * </li>
92       * <li>Read to-many relationship list:<br>
93       * <code>List exhibits = (List)painting.readNestedProperty("toGallery.exhibitArray");</code>
94       * <br>
95       * <br>
96       * </li>
97       * <li>Read to-many relationship in the middle of the path <b>(throws exception)</b>:<br>
98       * <code>String name = (String)artist.readNestedProperty("paintingArray.paintingName");</code>
99       * <br>
100      * <br>
101      * </li>
102      * </ul>
103      * 
104      * @since 1.0.5
105      */
106     public Object   readNestedProperty(String   path);
107 
108     /**
109      * Returns a value of the property identified by propName. Resolves faults if needed.
110      * This method can safely be used instead of or in addition to the auto-generated
111      * property accessors in subclasses of CayenneDataObject.
112      */
113     public Object   readProperty(String   propName);
114 
115     /**
116      * Sets the property to the new value. Resolves faults if needed. This method can be
117      * safely used instead of or in addition to the auto-generated property modifiers to
118      * set simple properties. Note that to set to-one relationships use
119      * {@link #setToOneTarget(String, DataObject, boolean)}.
120      * 
121      * @param propertyName a name of the bean property being modified.
122      * @param value a new value of the property.
123      */
124     public void writeProperty(String   propertyName, Object   value);
125 
126     /**
127      * Adds an object to a to-many relationship.
128      */
129     public void addToManyTarget(String   relationshipName, DataObject target, boolean setReverse);
130 
131     /**
132      * Removes an object from a to-many relationship.
133      */
134     public void removeToManyTarget(String   relationshipName, DataObject target, boolean unsetReverse);
135 
136     /**
137      * Sets to-one relationship to a new value. Resolves faults if needed. This method can
138      * safely be used instead of or in addition to the auto-generated property modifiers
139      * to set properties that are to-one relationships.
140      * 
141      * @param relationshipName a name of the bean property being modified - same as the
142      *            name of ObjRelationship.
143      * @param value a new value of the property.
144      * @param setReverse whether to update the reverse relationship pointing from the old
145      *            and new values of the property to this object.
146      */
147     public void setToOneTarget(
148             String   relationshipName,
149             DataObject value,
150             boolean setReverse);
151 
152     /**
153      * @deprecated since 3.0 users must use callbacks instead. This method is no longer
154      *             invoked by Cayenne runtime.
155      * @see LifecycleListener
156      */
157     public void fetchFinished();
158 
159     /**
160      * Returns a version of a DataRow snapshot that was used to create this object.
161      * 
162      * @since 1.1
163      */
164     public long getSnapshotVersion();
165 
166     /**
167      * @since 1.1
168      */
169     public void setSnapshotVersion(long snapshotVersion);
170 }
171
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags