View Javadoc

1   // 
2   // Copyright (c) 2003, Caltha - Gajda, Krzewski, Mach, Potempski Sp.J. 
3   // All rights reserved. 
4   // 
5   // Redistribution and use in source and binary forms, with or without modification,  
6   // are permitted provided that the following conditions are met: 
7   //  
8   // * Redistributions of source code must retain the above copyright notice,  
9   //	 this list of conditions and the following disclaimer. 
10  // * Redistributions in binary form must reproduce the above copyright notice,  
11  //	 this list of conditions and the following disclaimer in the documentation  
12  //	 and/or other materials provided with the distribution. 
13  // * Neither the name of the Caltha - Gajda, Krzewski, Mach, Potempski Sp.J.  
14  //	 nor the names of its contributors may be used to endorse or promote products  
15  //	 derived from this software without specific prior written permission. 
16  // 
17  // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"  
18  // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED  
19  // WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
20  // IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,  
21  // INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,  
22  // BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
23  // OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,  
24  // WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)  
25  // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE  
26  // POSSIBILITY OF SUCH DAMAGE. 
27  // 
28  package org.objectledge.database.persistence;
29  
30  import java.util.List;
31  
32  import org.objectledge.database.Database;
33  
34  /***
35   * Provides Object-Relational DB mapping.
36   * 
37   * @author <a href="mailto:rafal@caltha.pl">Rafal Krzewski</a>
38   * @author <a href="mailto:pablo@caltha.pl">Pawel Potempski</a>
39   * @version $Id: Persistence.java,v 1.10 2004/02/27 12:23:23 pablo Exp $
40   */
41  public interface Persistence
42  {
43      // PersistenceSystem interface //////////////////////////////////////////
44  
45      /***
46       * Loads an object from the database.
47       *
48       * @param id the identifier of the object.
49       * @param factory the object instance factory.
50       * @return the presistent object.
51       * @throws PersistenceException if any exception occured.
52       */
53      public Persistent load(long id, PersistentFactory factory)
54          throws PersistenceException;
55  
56      /***
57       * Loads objects from the database.
58       *
59       * <p>Note that joins are not supported. This package provides a means of
60       * converting objects to rows in a table and vice versa. If you want more,
61       * you need some different tool.</p>
62       *
63       * @param where the where clause to be used in the query
64       * @param factory the object instance factory.
65       * @return the list of presistent objects.
66       * @throws PersistenceException if any exception occured.
67       */
68      public List load(String where, PersistentFactory factory) throws PersistenceException;
69  
70      /***
71       * Saves an object in the database.
72       *
73       * @param object the object to be saved.
74       * @throws PersistenceException if any exception occured.
75       */
76      public void save(Persistent object) throws PersistenceException;
77  
78      /***
79       * Reverts the object to the saved state.
80       *
81       * @param object the object to have it's state restored.
82       * @throws PersistenceException if any exception occured.
83       * @throws IllegalStateException if no state has been saved yet for the
84       *         object in question.
85       */
86      public void revert(Persistent object)
87          throws PersistenceException, IllegalStateException;
88  
89      /***
90       * Removes an object from the database.
91       *
92       * @param object the object to be removed.
93       * @throws PersistenceException if any exception occured.
94       */
95      public void delete(Persistent object) throws PersistenceException;
96  
97      /***
98       * Removes the objects from the database.
99       *
100      * @param where the where clause to be used in the query
101      * @param factory the object instance factory.
102      * @throws PersistenceException if any exception occured.
103      */
104     public void delete(String where, PersistentFactory factory) throws PersistenceException;
105 
106     /***
107      * An utility method for checking for existence of rows.
108      *
109      * @param table the table to be checked.
110      * @param where the condition.
111      * @return <code>true</code> if the <code>condition</code> is true for one
112      *         or more rows in the <code>table</code>.
113      * @throws PersistenceException if any exception occured.
114      */
115     public boolean exists(String table, String where) throws PersistenceException;
116     
117     /***
118      * An utility method for checking the number of matching rows.
119      *
120      * @param table the table to be chcked.
121      * @param where the condition.
122      * @return the number of <code>table</code> matching the condition.
123      * @throws PersistenceException if any exception occured.
124      */
125     public int count(String table, String where) throws PersistenceException;
126     
127     /***
128      * Get the database component used by persistence.
129      * @return the database.
130      */
131     public Database getDatabase();
132 }