Cacheable


1   /*
2   
3      Derby - Class org.apache.derby.iapi.services.cache.Cacheable
4   
5      Licensed to the Apache Software Foundation (ASF) under one or more
6      contributor license agreements.  See the NOTICE file distributed with
7      this work for additional information regarding copyright ownership.
8      The ASF licenses this file to you under the Apache License, Version 2.0
9      (the "License"); you may not use this file except in compliance with
10     the License.  You may obtain a copy of the License at
11  
12        http://www.apache.org/licenses/LICENSE-2.0
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   */
21  
22  package org.apache.derby.iapi.services.cache;
23  
24  import org.apache.derby.iapi.error.StandardException;
25  
26  /**
27      Any object that implements this interface can be cached using the services of
28      the CacheManager/CacheFactory. In addition to implementing this interface the
29      class must be public and it must have a public no-arg constructor. This is because
30      the cache manager will construct objects itself and then set their identity
31      by calling the setIdentity method.
32      <P>
33      A Cacheable object has five states:
34      <OL>
35      <OL>
36      <LI> No identity - The object is only accessable by the cache manager
37      <LI> Identity, clean, unkept - The object has an identity, is clean but is only accessable by the cache manager
38      <LI> Identity, clean, kept - The object has an identity, is clean, and is in use by one or more threads 
39      <LI> Identity, kept, dirty - The object has an identity, is dirty, and is in use by one or more threads 
40      <LI> Identity, unkept, dirty - The object has an identity, is dirty but is only accessable by the cache manager
41      </OL>
42      </OL>
43      <BR>
44      While the object is kept it is guaranteed
45      not to change identity. While it is unkept no-one outside of the
46      cache manager can have a reference to the object.
47      The cache manager returns kept objects and they return to the unkept state
48      when all the current users of the object have released it.
49      <BR>
50      It is required that the object can only move into a dirty state while it is kept.
51  
52      <BR> MT - Mutable : thread aware - Calls to Cacheable method must only be made by the
53      cache manager or the object itself.
54  
55      @see CacheManager
56      @see CacheFactory
57      @see Class#newInstance
58  */
59  public interface Cacheable  {
60  
61      /**
62          Set the identity of the object.
63          <p>
64          Set the identity of the object to represent an item that already exists,
65          e.g. an existing container.
66          The object will be in the No Identity state,
67          ie. it will have just been created or clearIdentity() was just called. 
68          <BR>
69          The object must copy the information out of key, not just store a reference to key.
70          After this call the expression getIdentity().equals(key) must return true.
71          <BR>
72          If the class of the object needs to change (e.g. to support a different format)
73          then the object should create a new object, call its initParameter() with the parameters
74          the original object was called with, set its identity and return a reference to it. The cache
75          manager will discard the reference to the old object. 
76          <BR>
77          If an exception is thrown the object must be left in the no-identity state.
78  
79          <BR> MT - single thread required - Method must only be called be cache manager
80          and the cache manager will guarantee only one thread can be calling it.
81  
82          @return an object reference if the object can take on the identity, null otherwise.
83  
84          @exception StandardException Standard Cloudscape Policy
85  
86          @see CacheManager#find
87  
88      */
89      public Cacheable setIdentity(Object   key) throws StandardException;
90  
91      /**
92          Create a new item.
93          <p>
94          Create a new item and set the identity of the object to represent it.
95          The object will be in the No Identity state,
96          ie. it will have just been created or clearIdentity() was just called. 
97          <BR>
98          The object must copy the information out of key, not just store a reference to key
99          if the key is not immutable.
100         After this call the expression getIdentity().equals(key) must return true.
101         <BR>
102         <BR>
103         If the class of the object needs to change (e.g. to support a different format)
104         then the object should create a new object, call its initParameter() with the parameters
105         the original object was called with, set its identity and return a reference to it. The cache
106         manager will discard the reference to the old object. 
107         <BR>
108         If an exception is thrown the object must be left in the no-identity state.
109 
110         <BR> MT - single thread required - Method must only be called be cache manager
111         and the cache manager will guarantee only one thread can be calling it.
112 
113         @return an object reference if the object can take on the identity, null otherwise.
114 
115         @exception StandardException If forCreate is true and the object cannot be created.
116 
117         @see CacheManager#create
118 
119     */
120     public Cacheable createIdentity(Object   key, Object   createParameter) throws StandardException;
121 
122 
123     /**
124         Put the object into the No Identity state. 
125 
126         <BR> MT - single thread required - Method must only be called be cache manager
127         and the cache manager will guarantee only one thread can be calling it.
128 
129     */
130     public void clearIdentity();
131 
132     /**
133         Get the identity of this object.
134 
135         <BR> MT - thread safe.
136 
137     */
138     public Object   getIdentity();
139 
140 
141     /**
142         Returns true of the object is dirty. 
143         May be called when the object is kept or unkept.
144 
145         <BR> MT - thread safe 
146 
147     */
148     public boolean isDirty();
149 
150     /**
151         Clean the object.
152         It is up to the object to ensure synchronization of the isDirty()
153         and clean() method calls.
154         <BR>
155         If forRemove is true then the 
156         object is being removed due to an explict remove request, in this case
157         the cache manager will have called this method regardless of the
158         state of the isDirty() 
159 
160         <BR>
161         If an exception is thrown the object must be left in the clean state.
162 
163         <BR> MT - thread safe - Can be called at any time by the cache manager, it is the
164         responsibility of the object implementing Cacheable to ensure any users of the
165         object do not conflict with the clean call.
166 
167         @exception StandardException Standard Cloudscape error policy.
168 
169     */
170     public void clean(boolean forRemove) throws StandardException;
171 }
172 
173
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags