View Javadoc

    1   /***
    2    * @(#)JDOService.java
    3    *
    4    * JFoxSOAF, Service-Oriented Application Framework
    5    *
    6    * Copyright(c) JFoxSOAF Team
    7    *
    8    * Licensed under the GNU LGPL, Version 2.1 (the "License");
    9    * you may not use this file except in compliance with the License.
    10   * You may obtain a copy of the License at
    11   *
    12   * http://www.gnu.org/copyleft/lesser.html
    13   *
    14   * Unless required by applicable law or agreed to in writing, software
    15   * distributed under the License is distributed on an "AS IS" BASIS,
    16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    17   * See the License for the specific language governing permissions and
    18   * limitations under the License.
    19   *
    20   * For more information, please visit:
    21   * http://www.jfox.cn/confluence/display/JFoxSOAF/Home
    22   * http://www.huihoo.org/jfox/jfoxsoaf
    23   */
    24
    25  package org.huihoo.jfox.soaf.services.persistence;
    26
    27  import java.util.Collection;
    28  import java.util.Map;
    29
    30  import javax.jdo.JDOException;
    31  import javax.jdo.PersistenceManager;
    32
    33  import org.huihoo.jfox.soaf.exception.DAOException;
    34
    35  /***
    36   * <p>
    37   * JDO persistence service wrapper.
    38   * </p>
    39   *
    40   * @author <a href="mailto:founder_chen@yahoo.com.cn">Peter Cheng </a>
    41   * @version $Revision:$ $Date:$
    42   * @version Revision: 1.0
    43   */
    44
    45  public interface JdoService {
    46
    47      /***
    48       * The Transaction instance is always associated with exactly one
    49       * PersistenceManager.
    50       *
    51       * @return PersistenceManager
    52       * @throws JDOException
    53       */
    54      public PersistenceManager getPersistenceManager() throws JDOException;
    55
    56      /***
    57       * Begin a transaction.
    58       *
    59       * @throws JDOException
    60       */
    61      public void beginTransaction() throws JDOException;
    62
    63      /***
    64       * Commit the current transaction.
    65       *
    66       * @throws JDOException
    67       */
    68      public void commit() throws JDOException;
    69
    70      /***
    71       * Roll back the current transaction.
    72       *
    73       * @throws JDOException
    74       */
    75      public void rollback() throws JDOException;
    76
    77      /***
    78       * Close this PersistenceManager so that no further requests may be made on
    79       * it.
    80       */
    81      public void close() throws JDOException;
    82
    83      /***
    84       * The ObjectId returned by this method represents the JDO identity of the
    85       * instance.
    86       *
    87       * @param object - the PersistenceCapable instance
    88       * @return - the ObjectId of the instance
    89       * @throws DAOException
    90       */
    91      public Object getObjectById(Object oid) throws JDOException, DAOException;
    92
    93      /***
    94       * Looks up the instance of the given type with the given key.
    95       *
    96       * @param clazz
    97       * @param oid
    98       * @return the corresponding persistent instance
    99       * @throws DAOException
    100      */
    101     public Object getObjectById(Class clazz, Object oid) throws JDOException,
    102             DAOException;
    103
    104     /***
    105      * This method locates a persistent instance in the cache of instances
    106      * managed by this PersistenceManager.
    107      *
    108      * @param object
    109      * @param validate
    110      * @return the PersistenceCapable instance with the specified ObjectId
    111      * @throws JDOException
    112      * @throws DAOException
    113      */
    114     public Object getObjectById(Object oid, boolean validate)
    115             throws JDOException, DAOException;
    116
    117     /***
    118      * The ObjectId returned by this method represents the JDO identity of the
    119      * instance. The ObjectId is a copy (clone) of the internal state of the
    120      * instance, and changing it does not affect the JDO identity of the
    121      * instance.
    122      *
    123      * @param object
    124      * @return the ObjectId of the instance
    125      * @throws JDOException
    126      * @throws DAOException
    127      */
    128     public Object getObjectId(Object pc) throws JDOException, DAOException;
    129
    130     /***
    131      * Return the Class that implements the JDO Identity for the specified
    132      * PersistenceCapable class.
    133      *
    134      * @param clazz - cls - the PersistenceCapable Class
    135      * @return the Class of the ObjectId of the parameter
    136      * @throws JDOException
    137      * @throws DAOException
    138      */
    139     public Class getObjectIdClass(Class clazz) throws JDOException,
    140             DAOException;
    141
    142     /***
    143      * Return the objects with the given oids.
    144      *
    145      * @param oids
    146      * @return the objects that were looked up, in the same order as the oids
    147      *         parameter.
    148      * @throws JDOException
    149      * @throws DAOException
    150      */
    151     public Collection getObjectsById(Collection oids) throws JDOException,
    152             DAOException;
    153
    154     /***
    155      * Return the objects with the given oids.
    156      *
    157      * @param oids
    158      * @param validate validate - if true, the existance of the objects in the
    159      *            datastore will be validated.
    160      * @return the objects that were looked up, in the same order as the oids
    161      *         parameter.
    162      * @throws JDOException
    163      * @throws DAOException
    164      */
    165     public Collection getObjectsById(Collection oids, boolean validate)
    166             throws JDOException, DAOException;
    167
    168     /***
    169      * Return the objects with the given oids. This method is equivalent to
    170      * calling getObjectsById(Object[],boolean) with the validate flag true.
    171      *
    172      * @param oids - the oids of the objects to return
    173      * @return the objects that were looked up, in the same order as the oids
    174      *         parameter.
    175      */
    176     public Object[] getObjectsById(Object[] oids) throws JDOException,
    177             DAOException;
    178
    179     /***
    180      * Return the objects with the given oids.
    181      *
    182      * @param oids - the oids of the objects to return
    183      * @param validate - validate - if true, the existance of the objects in the
    184      *            datastore will be validated.
    185      * @return the objects that were looked up, in the same order as the oids
    186      *         parameter.
    187      */
    188     public Object[] getObjectsById(Object[] oids, boolean validate)
    189             throws JDOException, DAOException;
    190
    191     /***
    192      * @param clazz
    193      * @return
    194      * @throws JDOException
    195      * @throws DAOException
    196      */
    197     public Collection query(Class clazz) throws JDOException, DAOException;
    198
    199     /***
    200      * Query with the Class of the candidate instances and filter
    201      *
    202      * @param clazz
    203      * @return the filtered Collection
    204      * @throws JDOException
    205      * @throws DAOException
    206      */
    207     public Collection query(Class clazz, String filter) throws JDOException,
    208             DAOException;
    209
    210     /***
    211      * Query with the Class of the candidate instances and filter
    212      *
    213      * @param clazz
    214      * @return the filtered Collection
    215      * @throws JDOException
    216      * @throws DAOException
    217      */
    218     public Collection query(Class clazz, String filter, String ordering)
    219             throws JDOException, DAOException;
    220
    221     /***
    222      * Query with the Class of the candidate instances and filter
    223      *
    224      * @param clazz
    225      * @return the filtered Collection
    226      * @throws JDOException
    227      * @throws DAOException
    228      */
    229     public Collection queryWithMap(Class clazz, String filter,
    230             String parameters, Map values) throws JDOException, DAOException;
    231
    232     /***
    233      * Query with the Class of the candidate instances and filter
    234      *
    235      * @param clazz
    236      * @return the filtered Collection
    237      * @throws JDOException
    238      * @throws DAOException
    239      */
    240     public Collection queryWithMap(Class clazz, String filter, String ordering,
    241             String parameters, Map values) throws JDOException, DAOException;
    242
    243     /***
    244      * Query with the Class of the candidate instances and filter
    245      *
    246      * @param clazz
    247      * @return the filtered Collection
    248      * @throws JDOException
    249      * @throws DAOException
    250      */
    251     public Collection queryWithMap(Class clazz, String filter,
    252             String parameters, Object[] values) throws JDOException,
    253             DAOException;
    254
    255     /***
    256      * Query with the Class of the candidate instances and filter
    257      *
    258      * @param clazz
    259      * @return the filtered Collection
    260      * @throws JDOException
    261      * @throws DAOException
    262      */
    263     public Collection queryWithMap(Class clazz, String filter, String ordering,
    264             String parameters, Object[] values) throws JDOException,
    265             DAOException;
    266
    267     /***
    268      * Query with the Class of the candidate instances, candidate Collection.
    269      *
    270      * @param clazz
    271      * @return the filtered Collection.
    272      * @throws JDOException
    273      * @throws DAOException
    274      */
    275     public Collection query(Class clazz, Collection coll) throws JDOException,
    276             DAOException;
    277
    278     /***
    279      * Query with the Class of the candidate instances, candidate Collection,
    280      * and filter.
    281      *
    282      * @param clazz
    283      * @return the filtered Collection.
    284      * @throws JDOException
    285      * @throws DAOException
    286      */
    287     public Collection query(Class clazz, Collection coll, String filter)
    288             throws JDOException, DAOException;
    289
    290     /***
    291      * Query using elements from another Query.
    292      *
    293      * @param clazz
    294      * @return the filtered Collection.
    295      * @throws JDOException
    296      * @throws DAOException
    297      */
    298     public Collection query(Object object) throws JDOException, DAOException;
    299
    300     /***
    301      * Query instance using the specified String as the single-string
    302      * representation of the query.
    303      *
    304      * @param clazz
    305      * @return the filtered Collection.
    306      * @throws JDOException
    307      * @throws DAOException
    308      */
    309     public Collection query(String queryStr) throws JDOException, DAOException;
    310
    311     /***
    312      * Mark an instance as no longer needed in the cache
    313      *
    314      * @param pc - the instance to evict from the cache.
    315      */
    316     public void evict(Object object) throws JDOException, DAOException;
    317
    318     /***
    319      * Mark all persistent-nontransactional instances as no longer needed in the
    320      * cache.
    321      *
    322      * @throws JDOException
    323      * @throws DAOException
    324      */
    325     public void evictAll() throws JDOException, DAOException;
    326
    327     /***
    328      * Mark a Collection of instances as no longer needed in the cache.
    329      *
    330      * @param pcs
    331      * @throws JDOException
    332      * @throws DAOException
    333      */
    334     public void evictAll(Collection coll) throws JDOException, DAOException;
    335
    336     /***
    337      * Mark an array of instances as no longer needed in the cache.
    338      *
    339      * @param pcs
    340      * @throws JDOException
    341      * @throws DAOException
    342      */
    343     public void evictAll(Object[] objects) throws JDOException, DAOException;
    344
    345     /***
    346      * Flushes all dirty, new, and deleted instances to the data store. It has
    347      * no effect if a transaction is not active.
    348      *
    349      * @throws JDOException
    350      * @throws DAOException
    351      */
    352     public void flush() throws JDOException, DAOException;
    353
    354     /***
    355      * Make the transient instance persistent in this PersistenceManager.
    356      *
    357      * @param object - a transient instance of a Class that implements
    358      *            PersistenceCapable
    359      * @throws JDOException
    360      * @throws DAOException
    361      */
    362     public void makePersistent(Object object) throws JDOException, DAOException;
    363
    364     /***
    365      * Make a Collection of instances persistent.
    366      *
    367      * @param coll - a Collection of transient instances
    368      */
    369     public void makePersistentAll(Collection coll) throws JDOException,
    370             DAOException;
    371
    372     /***
    373      * Make an array of instances persistent.
    374      *
    375      * @param pcs
    376      */
    377     public void makePersistentAll(Object[] objects) throws JDOException,
    378             DAOException;
    379
    380     /***
    381      * Delete the persistent instance from the data store.
    382      *
    383      * @param pc
    384      * @throws JDOException
    385      * @throws DAOException
    386      */
    387     public void deletePersistent(Object object) throws JDOException,
    388             DAOException;
    389
    390     /***
    391      * Delete a Collection of instances from the data store.
    392      *
    393      * @param pcs
    394      * @throws JDOException
    395      * @throws DAOException
    396      */
    397     public void deletePersistentAll(Collection coll) throws JDOException,
    398             DAOException;
    399
    400     /***
    401      * Delete an array of instances from the data store.
    402      *
    403      * @param pcs
    404      */
    405     public void deletePersistentAll(Object[] objects) throws JDOException, DAOException;
    406
    407 }