PMapper


1   /**
2    * JORM: an implementation of a generic mapping system for persistent Java
3    *       objects. Two mapping are supported: to RDBMS and to binary files.
4    * Copyright (C) 2001-2003 France Telecom R&D - INRIA
5    *
6    * This library is free software; you can redistribute it and/or
7    * modify it under the terms of the GNU Lesser General Public
8    * License as published by the Free Software Foundation; either
9    * version 2 of the License, or (at your option) any later version.
10   *
11   * This library is distributed in the hope that it will be useful,
12   * but WITHOUT ANY WARRANTY; without even the implied warranty of
13   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14   * Lesser General Public License for more details.
15   *
16   * You should have received a copy of the GNU Lesser General Public
17   * License along with this library; if not, write to the Free Software
18   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19   *
20   * Contact: jorm-team@objectweb.org
21   *
22   */
23  
24  package org.objectweb.jorm.api;
25  
26  import org.objectweb.jorm.metainfo.api.Manager;
27  import org.objectweb.jorm.type.api.PTypeSpace;
28  import org.objectweb.jorm.type.api.PExceptionTyping;
29  import org.objectweb.medor.eval.prefetch.api.PrefetchCache;
30  
31  /**
32   * The <b>PMapper</b> interface defines a JORM mapper as an object that mainly
33   * maintains the set of JORM classes that it maps on a particular DS. It relies
34   * on JCA as a means to access a DS.
35   * It enables to access to the meta-information associated to JORM classes at
36   * runtime.
37   * Before being able to request the load of meta-information at mapping time,
38   * the mapper should have been assigned a mapping name, a meta-information
39   * manager, as well as a parser.
40   * @author  P. Dechamboux
41   */
42  public interface PMapper extends PMappingStructuresManager {
43      final String   PCLASSMAPPINGAPPENDER = "Mapping";
44      final String   PBINDINGAPPENDER = "Binding";
45      final String   JORMPROPFILE = "jorm.properties";
46  
47      /**
48       * Closes the given connection which has been allocated previously using
49       * getConnection.
50       * @param conn  The concerned connection.
51       */
52      void closeConnection(Object   conn) throws PException;
53  
54      /**
55       * Constructs a "mapped name" starting from a JORM class name. For example,
56       * "foo" class name produces "<getProjectName()>.foo", while "p1.p2.foo"
57       * produces "p1.p2.<getProjectName()>.foo".
58       * @param cn    The JORM class name.
59       */
60      String   cn2mn(String   cn);
61  
62      /**
63       * Allocates a connection for accessing the underlying DS.
64       */
65      Object   getConnection() throws PException;
66  
67      /**
68       * Allocates a connection for accessing the underlying DS knowing additional
69       * context information.
70       * @param ctxt  Context information used to allocate the connection.
71       */
72      Object   getConnection(Object   ctxt) throws PException;
73  
74      /**
75       * Allocates a connection for accessing the underlying DS knowing additional
76       * context information.
77       * @param connectionContext Context information used to allocate the connection.
78       * @param user is the identifier of the connection user (working set
79       * or transaction id).
80       */
81      Object   getConnection(Object   connectionContext, Object   user) throws PException;
82  
83      /**
84       * The name yielded by this method defines what kind of PMapper is used
85       * on a particular DS.
86       * @return  The name defining the PMapper kind.
87       */
88      String   getMapperName();
89  
90      /**
91       * Retrieves the PMappingStructuresManager associated with this mapper.
92       * @return The associated PMappingStructuresManager.
93       */
94      PMappingStructuresManager getPMappingStructuresManager();
95  
96      /**
97       * It looks for the PClassMapping object associated to a JORM class within
98       * this PMapper.
99       * @return  The PClassMapping that maps the corresponding class, or null if
100      *          none exists
101      */
102     PClassMapping lookup(String   classname);
103 
104     /**
105      * It registers a PClassMapping associated to a particular JORM class within
106      * this PMapper. It initializes the storage structures if necessary. It
107      * previously removes them if the "dsrem" flag is set. If the mapper is
108      * ready to manage the meta-information, it is loaded for this JORM class.
109      * @param pcm   The class mapping to add to this mapper.
110      * @exception PExceptionIO  It is raised when an I/O problem occurs within
111      *                          the underlying DS.
112      * @exception PExceptionProtocol    It is raised when a problem occurs
113      *                                  during initialisation of the class
114      *                                  mapping.
115      * @exception PExceptionTyping  It is raised when a typing problem occurs
116      *                              during initialisation of the class mapping.
117      */
118     void map(PClassMapping pcm)
119             throws PException;
120 
121     /**
122      * It registers a PClassMapping associated to a particular JORM class within
123      * this PMapper. It initializes the storage structures if necessary. It
124      * previously removes them if the "dsrem" flag is set. If the mapper is
125      * ready to manage the meta-information, it is loaded for this JORM class.
126      * @param conn  The connection to access to the underlying DS.
127      * @param pcm   The class mapping to add to this mapper.
128      * @exception PExceptionIO  It is raised when an I/O problem occurs within
129      *                          the underlying DS.
130      * @exception PExceptionProtocol    It is raised when a problem occurs
131      *                                  during initialisation of the class
132      *                                  mapping.
133      * @exception PExceptionTyping  It is raised when a typing problem occurs
134      *                              during initialisation of the class mapping.
135      */
136     void map(Object   conn, PClassMapping pcm)
137             throws PException;
138 
139     /**
140      * It registers a PClassMapping associated to a particular JORM class within
141      * this PMapper. It initializes the storage structures if necessary. It
142      * previously removes them if the "dsrem" flag is set. It also loads the
143      * meta-information related to this class if the "loadmeta" flag is set.
144      * @param conn  The connection to access to the underlying DS.
145      * @param pcm       The class mapping to add to this mapper.
146      * @param loadmeta  It specifies that meta-information should be loaded for
147      *                  this class to map.
148      * @exception PExceptionIO  It is raised when an I/O problem occurs within
149      *                          the underlying DS.
150      * @exception PExceptionProtocol    It is raised when a problem occurs
151      *                                  during initialisation of the class
152      *                                  mapping.
153      * @exception PExceptionTyping  It is raised when a typing problem occurs
154      *                              during initialisation of the class mapping.
155      */
156     void map(Object   conn, PClassMapping pcm, boolean loadmeta)
157             throws PException;
158 
159     /**
160      * Assigns a connection factory to this mapper.
161      * @exception PExceptionProtocol    It is raised if a connection factory
162      *                                  has already been assigned.
163      */
164     void setConnectionFactory(Object   cf) throws PException;
165 
166     /**
167      * Returns the connection factory associated to this mapper.
168      */
169     Object   getConnectionFactory();
170 
171     /**
172      * Assigns a prefetch cache to this mapper. It is optional.
173      * @exception PExceptionProtocol    It is raised if a prefetch cache
174      *                                  has already been assigned.
175      */
176     void setPrefetchCache(PrefetchCache pc) throws PException;
177 
178     /**
179      * Returns the prefetch cache associated to this mapper. It can be null.
180      */
181     PrefetchCache getPrefetchCache();
182 
183     /**
184      * It assigns the name of the mapper that is instanciated. It is mandatory
185      * to assign it at mapper initialization as the load of meta-information
186      * depends on it.
187      * @param mappername    The name of the mapper.
188      */
189     void setMapperName(String   mappername);
190 
191     /**
192      * It retrieves a meta-information Manager that may used by a parser in order
193      * to load the meta-information associated to JORM classes mapped within
194      * this PMapper.
195      * @return  The meta-information Manager assigned.
196      */
197     Manager getMetaInfoManager();
198 
199     /**
200      * It returns a PTypeSpace that may be used to create PType
201      * associated to JORM classes mapped within this PMapper.
202      */
203     PTypeSpace getPTypeSpace();
204 
205     /**
206      * Starts this mapper.
207      * @throws PException
208      */
209     void start() throws PException;
210 
211     /**
212      * Stops this mapper.
213      * @throws PException
214      */
215     void stop() throws PException;
216 
217     /**
218      * It unmaps a particular JORM class within this PMapper.
219      * @param classname The name of the JORM class to be unmapped.
220      */
221     void unmap(String   classname) throws PException;
222 
223     /**
224      * Adds the given mapper listener to this mapper. If it already exists,
225      * does nothing.
226      * @param listener  The corresponding listener.
227      */
228     void addMapperEventListener(PMapperListener listener);
229 
230     /**
231      * Removes the given mapper listener from this mapper. If it is not
232      * present among this list, does nothing.
233      * @param listener  The corresponding listener.
234      */
235     void removeMapperEventListener(PMapperListener listener);
236 
237     /**
238      * Creates a new PClassMapping for a gen class. It instanciates the relevant
239      * class wrt the type of mapper.
240      * @return
241      */
242     PClassMapping createGenClassMapping() throws PException;
243 }
244
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags