KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > commonj > sdo > ChangeSummary


1 /**
2  * <copyright>
3  *
4  * Service Data Objects
5  * Version 1.0
6  * Licensed Materials - Property of BEA and IBM
7  *
8  * (c) Copyright BEA Systems, Inc. and International Business Machines Corp 2003. All rights reserved.
9  *
10  * </copyright>
11  *
12  * $Id: ChangeSummary.java,v 1.1 2004/03/26 15:24:15 marcelop Exp $
13  */

14 package commonj.sdo;
15
16 import java.util.List JavaDoc;
17
18 /**
19  * A change summary is used to record changes to the objects in a {@link DataGraph data graph},
20  * allowing applications to efficiently and incrementally update back-end storage when required.
21  */

22 public interface ChangeSummary
23 {
24   /**
25    * Clears the list of {@link #getChangedDataObjects changes} and turns change logging on.
26    * @see #endLogging
27    * @see #isLogging
28    */

29   void beginLogging();
30
31   /**
32    * Turns change logging off.
33    * @see #beginLogging
34    * @see #isLogging
35    */

36   void endLogging();
37
38   /**
39    * Indicates whether change logging is on (<code>true</code>) or off (<code>false</code>).
40    * @return <code>true</code> if change logging is on.
41    * @see #beginLogging
42    * @see #endLogging
43    */

44   boolean isLogging();
45
46   /**
47    * Returns the {@link DataGraph data graph} associated with this change log.
48    * @return the data graph.
49    * @see DataGraph#getChangeSummary
50    */

51   DataGraph getDataGraph();
52
53   /**
54    * Returns a list consisting of all the {@link DataObject data objects} that have been changed while {@link #isLogging logging}.
55    * <p>
56    * The {@link #isCreated new} and modified objects in the list are references to objects that
57    * are {@link DataObject#getDataGraph contained} in the {@link #getDataGraph data graph} associated with this log.
58    * The {@link #isDeleted deleted} objects in the list are references to copies of the objects
59    * as they appeared at the time that event logging was first enabled;
60    * if the deleted objects have references to other objects,
61    * the references will also refer to copies of the target objects.
62    * @return a list of changed data objects.
63    * @see #isCreated(DataObject)
64    * @see #isDeleted(DataObject)
65    */

66   List JavaDoc /*DataObject*/ getChangedDataObjects();
67
68   /**
69    * Returns whether or not the specified data object was created while {@link #isLogging logging}.
70    * Any object that was added to the {@link #getDataGraph data graph}
71    * but was not {@link DataObject#getDataGraph contained} in the data graph when logging began,
72    * will be considered created.
73    * @param dataObject the data object in question.
74    * @return <code>true</code> if the specified data object was created.
75    * @see #getChangedDataObjects
76    */

77   boolean isCreated(DataObject dataObject);
78
79   /**
80    * Returns whether or not the specified data object was deleted while {@link #isLogging logging}.
81    * Any object that is not {@link DataObject#getDataGraph contained} by the {@link #getDataGraph data graph} will be considered deleted.
82    * @param dataObject the data object in question.
83    * @return <code>true</code> if the specified data object was deleted.
84    * @see #getChangedDataObjects
85    */

86   boolean isDeleted(DataObject dataObject);
87
88   /**
89    * A setting encapsulates a {@link Property property} and a corresponding single value of the property's {@link Property#getType type}.
90    */

91   public interface Setting
92   {
93     /**
94      * Returns the property of the setting.
95      * @return the setting property.
96      */

97     Property getProperty();
98
99     /**
100      * Returns the value of the setting.
101      * @return the setting value.
102      */

103     Object JavaDoc getValue();
104
105     /**
106      * Returns whether or not the property is set.
107      * @return <code>true</code> if the property is set.
108      */

109     boolean isSet();
110   }
111
112   /**
113    * Returns a list of {@link ChangeSummary.Setting settings}
114    * that represent the property values of the given <code>dataObject</code>
115    * at the point when logging {@link #beginLogging() began}.
116    * <p>In the case of a {@link #isDeleted(DataObject) deleted} object,
117    * the list will include settings for all the properties.
118    * @param dataObject the object in question.
119    * @return a list of settings.
120    * @see #getChangedDataObjects
121    */

122   List JavaDoc /*ChangeSummary.Setting*/ getOldValues(DataObject dataObject);
123 }
124
Popular Tags