View Javadoc

1   /* (c) Copyright 2003 Caleigo AB, All rights reserved. 
2    * 
3    * This library is free software; you can redistribute it and/or
4    * modify it under the terms of the GNU Lesser General Public
5    * License as published by the Free Software Foundation; either
6    * version 2.1 of the License, or (at your option) any later version.
7    * 
8    * This library is distributed in the hope that it will be useful,
9    * but WITHOUT ANY WARRANTY; without even the implied warranty of
10   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
11   * Lesser General Public License for more details.
12   * 
13   * You should have received a copy of the GNU Lesser General Public
14   * License along with this library; if not, write to the Free Software
15   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16   *  
17   */
18  
19  package org.caleigo.core;
20  
21  /*** <Description of IEntityDescriptor>
22  *
23  * @author Dennis Zikovic
24  * @version 1.00
25  * 
26  *//* 
27  *
28  * WHEN        WHO		WHY & WHAT
29  * ------------------------------------------------------------------------------
30  * 2001-03-12  Dennis Zikovic    Creation
31  */
32  public interface IEntityDescriptor extends java.io.Serializable
33  {
34      // Constants ---------------------------------------------------------------
35      
36      /*** Signifies that these enitities are handled as seperate units that can 
37       * be viewed and handled as isolated units.
38       */
39      public static final int MASTER_ENTITY = 0;
40      
41      /*** These entities are generally never viewed or handled as an isolated 
42       * seperate unit. They are genneraly always viewed and manipulated as 
43       * slaves or children to another entity type that generaly
44       * is a master entity.
45       */
46      public static final int SLAVE_ENTITY = 1;
47      
48      /*** Signifies that the purpose of this entity is only to link other entity 
49       * types together in N to N relationships. <BR>
50       */
51      public static final int LINK_ENTITY = 2;
52      
53      /*** Used for tables storing system constants that rarely or never changes. 
54       * These entities are generally cacheable with no time limit.
55       */
56      public static final int STATIC_ENTITY = 3;
57      
58      /*** Used for entities that are composites of other entities and therefore 
59       * can not specify another entity type. 
60       */
61      public static final int CUSTOM_ENTITY = 4;
62      
63      /*** Can be used to chech the result of getCacheTime().
64       */
65      public static final int NO_TIME_LIMIT = -1;
66      	
67      /*** Code name constant for the store action.
68       */
69      public static final String STORE_ACTION = "Store"; 
70      	
71      /*** Code name constant for the delete action.
72       */
73      public static final String DELETE_ACTION = "Delete"; 
74      
75      // Action methods ----------------------------------------------------------
76      
77      /*** Creates an entity with of the type described by this descriptor and
78       * loads it with default data.
79       */
80      public IEntity createEntity();
81          
82      /*** Creates an entity with of the type described by this descriptor and
83       * loads it with data from the provided property source.
84       */
85      public IEntity createEntity(IDataProvider propertySource);
86  
87      /*** Loads a selection of entities of the called descriptors type using
88       * the provided entity descriptor. The method uses the default data source
89       * for the entity type.
90       */
91      public ISelection loadSelection(Qualifier qualifier);
92  
93      /*** The load method returnes a single entity object intentified by the 
94       * provided indentity qualifier that must be able to uniquely identify
95       * a single entity instance.
96       */
97      public IEntity loadEntity(Qualifier identityQualifier);
98  
99      // Access methods ----------------------------------------------------------
100     
101     /*** Returns an identifying name that can be used to address the field in
102      * client software if the field descriptor for some reason is not available.
103      */
104     public String getCodeName();
105     
106     /*** Returns an identifying name used in communication with the data service
107      * layer. Should normally never be used by the client developer.
108      */ 
109     public String getSourceName();
110     
111     /*** Returns a displayable name for the entity.
112      */
113     public String getDisplayName();
114     
115     /*** Returns the class for the entities described by the entity descriptor.
116      */
117     public Class getEntityClass();
118     
119     /*** Returns the entity type signified by the constants... <p> 
120      * MASTER_ENTITY = Signifies that these enitities are handled as seperate 
121      * units that can be viewed and handled as isolated units. <BR>
122      * SLAVE_ENTITY = These entities are generally never viewed or handled as
123      * an isolated seperate unit. They are genneraly always viewed and 
124      * manipulated as slaves or children to another entity type that generaly
125      * is a master entity. <BR>
126      * LINK_ENTITY = Signifies that the purpose of this entity is only to link 
127      * other entity types together in N to N relationships. <BR>
128      * STATIC_ENTITY = Used for tables storing system constants that rarely or
129      * never changes. These entities are generally cacheable with no time limit. <BR>
130      * CUSTOM_ENTITY = Used for entities that are composites of other entities 
131      * and therefore can not specify another entity type. 
132      */
133     public int getEntityType();
134     
135     /*** Returns true if entities described by the called descriptor may be 
136      * created. If a store operation is called on a non-persistent entity
137      * of the described type an exception should be thrown.
138      */
139     public boolean isCreatable(); 
140     
141     /*** Returns true if entities described by the called descriptor may be 
142      * updated. If a store operation is called on a persistent entity
143      * of the described type an exception should be thrown.
144      */
145     public boolean isEditable(); 
146     
147     /*** Returns true if entities described by the called descriptor may be 
148      * deleted. If a store operation is called on a persistent entity
149      * of the described type an exception should be thrown.
150      */
151     public boolean isDeletable(); 
152     
153     /*** Returns the acceptable time in seconds to cache entities described
154      * by the descriptor. Zero means no caching is accepable and the constant 
155      * NO_TIME_LIMIT sinifies that there are no time limit when cacheing.
156      */
157     public int getCacheTime();
158     
159     /*** This routine should return true if it possible to view and select 
160      * between ALL existing entities. In other words if it possible to use 
161      * for instance a combo box to select between the entities. 
162      * This is generally true when the entity count is less then 20.
163      */  
164     public boolean isSelectable(); 
165     
166     /*** This routine should return true if it is meaningfull to display ALL 
167      * existing entities for a user at the same time. This is generally true
168      * when the entity count is less then 200.
169      */  
170     public boolean isListable();
171     
172     /*** This routine should return true if it "pays" for the system to cache 
173      * the entire table when accessing a single entity. This depends on many 
174      * factors, the size of the entities, the bandwith and the frequence of
175      * entity access. If the amount of entities exceds 2000 they generaly not
176      * considered cachable.
177      */  
178     public boolean isCacheable();
179     
180     /*** This routine should return true if it is acceptable for the system 
181      * to for any reason scan all existing entities of this type. In other 
182      * words if a tablescan is acceptable or should be avoided. If the amount
183      * of entities excedes a million this is generally not true.
184      */ 
185     public boolean isScanable();
186 	
187     /*** Returns the number of field descriptors that this entity descriptor
188      * contains. This includes both data and calculated field descriptors.
189      */
190     public int getFieldCount();
191     
192     /*** Returns the number of field descriptors that have persistent data or in 
193      * other words are not descendants to ICalculatedFieldDescriptor's that this
194      * entity descriptor contains.
195      */
196     public int getDataFieldCount();
197 	
198     /*** Returns a specific field descriptor from the entity descriptor addressed
199      * by its ordial index. May cast OutOfBoundException.
200      */
201     public IFieldDescriptor getFieldDescriptor(int index);
202     
203     /*** Returns a specific field descriptor from the entity descriptor addressed
204      * by its code name. May return null if the codeName was not identified.
205      */
206     public IFieldDescriptor getFieldDescriptor(String codeName);
207     
208     /*** Returns all field descriptors as an iterator.
209      */
210     public java.util.Iterator getFieldDescriptors();
211     
212     /*** Returns the DataSource descriptor that this entity is a part of.
213      */
214     public IDataSourceDescriptor getDataSourceDescriptor();
215     
216     /*** Reurns true if the provided field descriptor is a part the called 
217      * entity descriptor.
218      */
219     public boolean contains(IFieldDescriptor fieldDescriptor);
220     
221     /*** Returns the index of the provided field descriptor or a negative value
222      * if the field is not a part of the entity descriptor.
223      */
224     public int getFieldIndex(IFieldDescriptor fieldDescriptor);
225     
226     /*** Returns the index of the field descriptor with the provided code name 
227      * or a negative value if the field is not a part of the entity descriptor.
228      */
229     public int getFieldIndex(String codeName);
230     
231     /*** Access method that returns the number of IEntityRelation:s that has 
232      * the called entity descriptor as source or target. 
233      */ 
234     public int getEntityRelationCount();
235     
236     /*** Access method that returns the indexed IEntityRelation.
237      */
238     public IEntityRelation getEntityRelation(int index);
239         
240     /*** Returns the index of the IEntityRelation with the specified code name, or
241      * <code>-1</code> if no relation is found.
242      */
243     public int getEntityRelationIndex(String codeName);
244     
245     /*** Access method that returns an interator IEntityRelation
246      * with all relation objects that the descriptor is part of.
247      */
248     public java.util.Iterator getEntityRelations();
249     
250     /*** Access method that returns the number of IEntityAction objects that are 
251      * available for access from the called IEntityDescriptor.
252      */
253     public int getActionCount();
254     
255     /*** Returns the indexed IEntityAction.
256      */
257     public IEntityAction getAction(int index);
258     
259     /*** Returns the IEntityAction with the provided code name. Returns null if
260      * the code name could not be identified.
261      */
262     public IEntityAction getAction(String codeName);
263     
264     /*** Returns an iterator with all contained IEntityAction objects that are  
265      * available for access from the called IEntityDescriptor.
266      */
267     public java.util.Iterator getActions();
268     
269     /*** Returns en entity collator defining the natural order for the called
270      * entity descriptors entities. 
271      */
272     public EntityCollator getNaturalOrder();
273     
274     /*** Temporary solution!!! Should be moved!
275      */
276     public Class getHomeClass();
277     
278     /*** Temporary solution!!! Should be moved!
279      */
280     public Class getRemoteClass();
281     
282     /*** Temporary solution!!! Should be moved!
283      */
284     public String getJNDIName();    
285 }