View Javadoc

1   /*
2   Wotonomy: OpenStep design patterns for pure Java applications.
3   Copyright (C) 2000 Michael Powers
4   
5   This library is free software; you can redistribute it and/or
6   modify it under the terms of the GNU Lesser General Public
7   License as published by the Free Software Foundation; either
8   version 2.1 of the License, or (at your option) any later version.
9   
10  This library is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  Lesser General Public License for more details.
14  
15  You should have received a copy of the GNU Lesser General Public
16  License along with this library; if not, see http://www.gnu.org
17  */
18  
19  package net.wotonomy.control;
20  
21  import net.wotonomy.foundation.NSArray;
22  
23  /***
24  * EODataSource is used by EODisplayGroup.fetch() to retrieve
25  * a list of objects to display.  When a display group has a
26  * data source, the display group will use the data source to
27  * populate the object list and to create new objects to be 
28  * displayed in the list, and will update the data source when
29  * objects are inserted or removed from the list. <br><br>
30  *
31  * In certain cases, as when a display group needs to populate
32  * a child display group to show a one-to-many relationship,
33  * the display group will call dataSourceQualifiedByKey to
34  * return a new data source that can vend objects associated
35  * with the specified key and then call qualifyWithRelationshipKey
36  * to specify the object and key that are the source of the 
37  * child relationship. <br><br>
38  *
39  * Concrete subclasses are expected to override fetch() and 
40  * are required to override insertObject and removeObject.
41  *
42  * @author michael@mpowers.net
43  * @author $Author: cgruber $
44  * @version $Revision: 894 $
45  */
46  public abstract class EODataSource
47  {
48      /***
49      * Creates a new object.  You should call 
50      * insertObject() to insert the new object into
51      * this data source.
52      * This implementation attempts to create a new
53      * instance of the class returned by 
54      * classDescriptionForObjects().
55      * Override to return an object specific to 
56      * your implementation.
57      * @return The newly created object, or null if
58      * new objects are not supported by this data source.
59      * @see #classDescriptionForObjects
60      */
61      public Object createObject ()
62      {
63          Object result = null;
64          EOClassDescription c = classDescriptionForObjects();
65          if ( c != null )
66          {
67              result = c.createInstanceWithEditingContext( editingContext(), null );                
68          }
69          return result;
70      }
71  
72      /***
73      * Inserts the specified object into this data source.
74      */
75      public abstract void insertObject ( Object anObject );
76  
77      /***
78      * Deletes the specified object from this data source.
79      */
80      public abstract void deleteObject ( Object anObject );
81  
82      /***
83      * Returns the editing context for this data source,
84      * or null if no editing context is used.
85      * This implementation returns null.
86      */
87      public EOEditingContext editingContext ()
88      {
89          return null;
90      }
91  
92      /***
93      * Returns a List containing the objects in this
94      * data source.  This implementation returns null.
95      */
96      public NSArray fetchObjects ()
97      {
98          return null;
99      }
100 
101     /***
102     * Returns a data source that is capable of
103     * manipulating objects of the type returned by 
104     * applying the specified key to objects 
105     * vended by this data source.
106     * @see #qualifyWithRelationshipKey
107     */
108     public abstract EODataSource 
109         dataSourceQualifiedByKey ( String aKey );
110 
111     /***
112     * Restricts this data source to vend those 
113     * objects that are associated with the specified 
114     * key on the specified object.
115     */
116     public abstract void 
117         qualifyWithRelationshipKey ( 
118         String aKey, Object anObject );
119 
120     /***
121     * Returns the description of the class of the
122     * objects that is vended by this data source,
123     * or null if this cannot be determined.
124     * This implementation returns null.
125     */
126     public EOClassDescription 
127         classDescriptionForObjects ()
128     {
129         return null;
130     }
131 
132 }
133 
134 /*
135  * $Log$
136  * Revision 1.2  2006/02/16 16:47:14  cgruber
137  * Move some classes in to "internal" packages and re-work imports, etc.
138  *
139  * Also use UnsupportedOperationExceptions where appropriate, instead of WotonomyExceptions.
140  *
141  * Revision 1.1  2006/02/16 13:19:57  cgruber
142  * Check in all sources in eclipse-friendly maven-enabled packages.
143  *
144  * Revision 1.5  2001/05/21 14:02:44  mpowers
145  * Corrected javadoc.
146  *
147  * Revision 1.4  2001/04/27 23:37:20  mpowers
148  * Now using EOClassDescription in the EODataSource class, as we should.
149  *
150  * Revision 1.3  2001/02/27 23:11:07  mpowers
151  * Removed object registration from createObject().
152  *
153  * Revision 1.2  2001/02/16 18:34:19  mpowers
154  * Implementing nested contexts.
155  *
156  * Revision 1.1.1.1  2000/12/21 15:46:38  mpowers
157  * Contributing wotonomy.
158  *
159  * Revision 1.3  2000/12/20 16:25:34  michael
160  * Added log to all files.
161  *
162  *
163  */
164