PBinding


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.naming.api.PName;
27  import org.objectweb.jorm.naming.api.PExceptionNaming;
28  import org.objectweb.jorm.type.api.PExceptionTyping;
29  
30  /**
31   * The <b>PBinding</b> interface defines the behaviour of binding objects used
32   * in order to control the I/Os between a data store instance and its
33   * associated memory instance.
34   * @author  R. Basset, P. Dechamboux
35   */
36  public interface PBinding {
37      static final byte ACTION_BIND = 0x01;
38      static final byte ACTION_UNBIND = 0x02;
39      static final byte ACTION_EXPORT = 0x03;
40      static final byte ACTION_UNEXPORT = 0x04;
41      static final byte ACTION_EXIST = 0x05;
42      static final byte ACTION_READ = 0x06;
43      static final byte ACTION_WRITE = 0x07;
44      /**
45       * The PBinding can perform read and write to the data store:
46       * It has a PName to reach an existing data store instance.
47       */
48      static final byte LIFECYCLE_ACTIVEFORIO = 0x01;
49      /**
50       * On the next <code>write</code> call, the PBinding will delete
51       * the data store instance associated to its PName, and release
52       * its PName:
53       * It has a PName to reach the related data store instance.
54       */
55      static final byte LIFECYCLE_DELTOWRITE = 0x02;
56      /**
57       * The PBinding has a PName to reach the data store, but the
58       * corresponding data store instance does not exist yet. It is thus ready
59       * to create the new data store instance.
60       *
61       */
62      static final byte LIFECYCLE_NEWTOWRITE = 0x03;
63      /**
64       * The PBinding does not have any PName to reach a data store instance.
65       */
66      static final byte LIFECYCLE_NOTBOUND = 0x04;
67      /**
68       * This is not a real state for a PBinding. It is used when a transition
69       * leads to a protocol error.
70       */
71      static final byte LIFECYCLE_ERROR = 0x05;
72  
73      /**
74       * It assigns a DSI represented by the PName passed as a parameter to this
75       * PBinding. This thus changes the link to the data store instance if one
76       * has been already assigned. The state changed to
77       * LIFECYCLE_ACTIVEFORIO.
78       * @param pn    The new PName to associate to this binding. This name
79       *              must belong to the binder associated to this binding.
80       * @exception PExceptionNaming  It is raised when there is a problem for the
81       *                              associated binder to manage this PName.
82       */
83      void bind(PName pn) throws PException;
84  
85      /**
86       * It verifies if the DSI attached to this binding exists within the DS.
87       * @param conn  The connection that can be used to refer to the DS.
88       * @return  It returns true if the DSI exists.
89       * @exception PExceptionIO  It is raised when a problem occured while
90       *                          accessing to the DS.
91       * @exception PExceptionNaming  It is raised when there is a problem for the
92       *                              associated binder to manage this PName.
93       * @exception PExceptionProtocol    It is raised when it is called with a
94       *                                  state different from the following ones:
95       *                                  LIFECYCLE_ACTIVEFORIO
96       */
97      boolean exist(Object   conn) throws PException;
98  
99      /**
100      * It creates a new PName for this binding, the binding state
101      * is normally changed to LIFECYCLE_NEWTOWRITE, and the link to a data
102      * store instance if it existed is removed.
103      * @param conn  The connection that can be used to refer to the DS.
104      * @return  The new PName assigned to this binding.
105      * @exception PExceptionIO  It is raised when a problem occured while
106      *                          accessing to the DS.
107      * @exception PExceptionNaming  It is raised when the associated binder
108      *                              does not manage to create a new name.
109      * @exception PExceptionProtocol    It is raised when it is called with a
110      *                                  state different from the following ones:
111      *                                  LIFECYCLE_ACTIVEFORIO
112      *                                  LIFECYCLE_DELTOWRITE
113      *                                  LIFECYCLE_NEWTOWRITE
114      */
115     PName export(Object   conn) throws PException;
116 
117     /**
118      * It creates a new PName for this binding, the binding state
119      * is normally changed to LIFECYCLE_NEWTOWRITE, and the link to a data
120      * store instance if it existed is removed.
121      * @param conn  The connection that can be used to refer to the DS.
122      * @param hints     Any information relevant for name creation.
123      * @return  The new PName assigned to this binding.
124      * @exception PExceptionIO  It is raised when a problem occured while
125      *                          accessing to the DS.
126      * @exception PExceptionNaming  It is raised when the associated binder
127      *                              does not manage to create a new name.
128      * @exception PExceptionProtocol    It is raised when it is called with a
129      *                                  state different from the following ones:
130      *                                  LIFECYCLE_ACTIVEFORIO
131      *                                  LIFECYCLE_DELTOWRITE
132      *                                  LIFECYCLE_NEWTOWRITE
133      */
134     PName export(Object   conn, Object   hints) throws PException;
135 
136     /**
137      * It gives access to the PClassMapping which manages this binding.
138      * @return  The PClassMapping which creates this binding.
139      */
140     PClassMapping getPClassMapping();
141 
142     /**
143      * It gives access to the PName, which designate a particular DSI,
144      * associated to this binding. It returns <code>null</code> if the binding
145      * has not been given a PName using a bind or export method.
146      * @return  The PName associated to this binding.
147      */
148     PName getPName();
149 
150     /**
151      * It yields the current status associated with this PBinding.
152      * @return  The corresponding status.
153      */
154     byte getStatus();
155 
156     /**
157      * It initialises a PBinding.
158      * @param pcm   The PBinding to initialise.
159      * @exception PExceptionProtocol    This PBinding cannot be managed by this
160      *                                  PClassMapping.
161      */
162     void init(PClassMapping pcm) throws PException;
163 
164     /**
165      * It reads the data store instance designated by the PName of this
166      * binding and transfers each attribute value to the accessor object.
167      * @param conn  The connection that can be used to refer to the DS.
168      * @param pa    The PAccessor used to access memory variables.
169      * @exception PExceptionIO  It is raised when a problem occured while
170      *                          accessing to the DS.
171      * @exception PExceptionNaming  It is raised when there is a problem for the
172      *                              associated binder to manage this PName.
173      * @exception PExceptionProtocol    It is raised when it is called with a
174      *                                  state different from the following ones:
175      *                                  LIFECYCLE_ACTIVEFORIO
176      */
177     void read(Object   conn, PAccessor pa) throws PException;
178 
179     /**
180      * It reads the data store instance designated by the PName of this
181      * binding and transfers each attribute value to the accessor object.
182      * This read method should be used when prefetching is requested.
183      * @param conn  The connection that can be used to refer to the DS.
184      * @param pa    The PAccessor used to access memory variables.
185      * @param txctx The transaction context that can be used in case of
186      *              prefetching.
187      * @exception PExceptionIO  It is raised when a problem occured while
188      *                          accessing to the DS.
189      * @exception PExceptionNaming  It is raised when there is a problem for the
190      *                              associated binder to manage this PName.
191      * @exception PExceptionProtocol    It is raised when it is called with a
192      *                                  state different from the following ones:
193      *                                  LIFECYCLE_ACTIVEFORIO
194      */
195     void read(Object   conn, PAccessor pa, Object   txctx) throws PException;
196 
197     /**
198      * It remove the association between a PName and a PBinding. No more PName
199      * is associated with this binding (it has no more link with a DSI).
200      * @exception PExceptionNaming  It is raised when there is a problem for the
201      *                              associated binder to manage this PName.
202      */
203     void unbind() throws PException;
204 
205     /**
206      * It prepares this PBinding to remove the data store instance from the
207      * data store. In order to actually remove this DSI, a call to write must
208      * follow.
209      * @param conn  The connection that can be used to refer to the DS.
210      * @exception PExceptionNaming  It is raised when there is a problem for the
211      *                              associated binder to manage this PName.
212      * @exception PExceptionProtocol    It is raised when it is called with a
213      *                                  state different from the following ones:
214      *                                  LIFECYCLE_ACTIVEFORIO
215      *                                  LIFECYCLE_DELTOWRITE
216      *                                  LIFECYCLE_NEWTOWRITE
217      */
218     void unexport(Object   conn) throws PException;
219 
220     /**
221      * It transfers each attribute value taken from the PAccessor
222      * object to the data store instance designated by the PName
223      * associated with this binding.
224      * @param conn  The connection that can be used to refer to the DS.
225      * @param pa    The PAccessor used to access memory variables.
226      * @exception PExceptionIO  It is raised when a problem occured while
227      *                          accessing to the DS.
228      * @exception PExceptionNaming  It is raised when there is a problem for the
229      *                              associated binder to manage this PName.
230      * @exception PExceptionProtocol    It is raised when it is called with a
231      *                                  state different from the following ones:
232      *                                  LIFECYCLE_ACTIVEFORIO
233      *                                  LIFECYCLE_NEWTOWRITE
234      *                                  LIFECYCLE_DELTOWRITE
235      * @exception PExceptionTyping  It is raised when a reference to be stored
236      *                              has a type incompatible with the respective
237      *                              field definition.
238      */
239     void write(Object   conn, PAccessor pa) throws PException;
240 }
241
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags