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  ;
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   /*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   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   /*ChangeSummary.Setting*/ getOldValues(DataObject dataObject); 
123 }
124
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags