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  import org.caleigo.core.exception.*;
22  
23  /*** IDataSerice is an IService that defines an abstract interface for generic
24   * database or other structured information access. The interface uses the CEL
25   * package and its defined structures to define, map and contain the information
26   * that are distributed using the interface. <BR><BR>
27   *
28   * Note the central importance of the IDataTransaction interface that defines
29   * data transaction abilities for the IDataService interface. If it is not
30   * possible for the underlaying data structure to provide trasaction management
31   * then the newTransaction() method should return null.
32   *
33   * @author  Dennis Zikovic
34   * @version 1.00
35   * 
36   *//* 
37   *
38   * WHEN        WHO               WHY & WHAT
39   * ------------------------------------------------------------------------------
40   * den 20 juli 2001  Dennis Zikovic    Creation
41   */
42  public interface IDataService extends org.caleigo.security.ISecureService
43  {
44      // Access methods ----------------------------------------------------------
45      
46      /*** This method provides access to the IDataSourceDescriptor that describes
47       * the entity meta structure of the information source that a specific 
48       * data service provides access to.
49       */
50      public IDataSourceDescriptor getDataSourceDescriptor();
51      
52      // Action methods ----------------------------------------------------------
53      
54      /*** The load method returnes a single entity object intentified by the 
55       * provided indentity qualifier that must be able to uniquely identify
56       * a single entity instance.
57       */
58      public IEntity load(IEntityDescriptor entityDescriptor, Qualifier identityQualifier) throws DataServiceException;
59      
60      /*** Loads a selection of entities identyfied by the provided qualifier.
61       */
62      public ISelection loadSelection(IEntityDescriptor entityDescriptor, Qualifier qualifier) throws DataServiceException;
63      
64      /*** Loads a selection of entities identyfied by the provided reusable 
65       * dataQuery object.
66       */
67      public ISelection loadSelection(DataQuery dataQuery) throws DataServiceException;
68      
69      /*** Stores a single entity object to the database.
70       */
71      public void store(IEntity entity) throws DataServiceException;
72      
73      /*** Deletes a single entity object to the database. Note that the emtity 
74       * object can still be used and even stored again posssibly to another 
75       * data source.
76       */
77      public void delete(IEntity entity) throws DataServiceException;
78      
79      /*** Reloads a single entity object from the database.
80       */
81      public void refresh(IEntity entity) throws DataServiceException;
82      
83      /*** Returns a new IDataTransaction object that can be used to batch 
84       * data operations and wrap them in a transaction.
85       */
86      public IDataTransaction newTransaction();
87      
88  }