001: /*
002:
003: Derby - Class org.apache.derby.iapi.services.cache.Cacheable
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.services.cache;
023:
024: import org.apache.derby.iapi.error.StandardException;
025:
026: /**
027: Any object that implements this interface can be cached using the services of
028: the CacheManager/CacheFactory. In addition to implementing this interface the
029: class must be public and it must have a public no-arg constructor. This is because
030: the cache manager will construct objects itself and then set their identity
031: by calling the setIdentity method.
032: <P>
033: A Cacheable object has five states:
034: <OL>
035: <OL>
036: <LI> No identity - The object is only accessable by the cache manager
037: <LI> Identity, clean, unkept - The object has an identity, is clean but is only accessable by the cache manager
038: <LI> Identity, clean, kept - The object has an identity, is clean, and is in use by one or more threads
039: <LI> Identity, kept, dirty - The object has an identity, is dirty, and is in use by one or more threads
040: <LI> Identity, unkept, dirty - The object has an identity, is dirty but is only accessable by the cache manager
041: </OL>
042: </OL>
043: <BR>
044: While the object is kept it is guaranteed
045: not to change identity. While it is unkept no-one outside of the
046: cache manager can have a reference to the object.
047: The cache manager returns kept objects and they return to the unkept state
048: when all the current users of the object have released it.
049: <BR>
050: It is required that the object can only move into a dirty state while it is kept.
051:
052: <BR> MT - Mutable : thread aware - Calls to Cacheable method must only be made by the
053: cache manager or the object itself.
054:
055: @see CacheManager
056: @see CacheFactory
057: @see Class#newInstance
058: */
059: public interface Cacheable {
060:
061: /**
062: Set the identity of the object.
063: <p>
064: Set the identity of the object to represent an item that already exists,
065: e.g. an existing container.
066: The object will be in the No Identity state,
067: ie. it will have just been created or clearIdentity() was just called.
068: <BR>
069: The object must copy the information out of key, not just store a reference to key.
070: After this call the expression getIdentity().equals(key) must return true.
071: <BR>
072: If the class of the object needs to change (e.g. to support a different format)
073: then the object should create a new object, call its initParameter() with the parameters
074: the original object was called with, set its identity and return a reference to it. The cache
075: manager will discard the reference to the old object.
076: <BR>
077: If an exception is thrown the object must be left in the no-identity state.
078:
079: <BR> MT - single thread required - Method must only be called be cache manager
080: and the cache manager will guarantee only one thread can be calling it.
081:
082: @return an object reference if the object can take on the identity, null otherwise.
083:
084: @exception StandardException Standard Cloudscape Policy
085:
086: @see CacheManager#find
087:
088: */
089: public Cacheable setIdentity(Object key) throws StandardException;
090:
091: /**
092: Create a new item.
093: <p>
094: Create a new item and set the identity of the object to represent it.
095: The object will be in the No Identity state,
096: ie. it will have just been created or clearIdentity() was just called.
097: <BR>
098: The object must copy the information out of key, not just store a reference to key
099: 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)
121: throws StandardException;
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: Returns true of the object is dirty.
142: May be called when the object is kept or unkept.
143:
144: <BR> MT - thread safe
145:
146: */
147: public boolean isDirty();
148:
149: /**
150: Clean the object.
151: It is up to the object to ensure synchronization of the isDirty()
152: and clean() method calls.
153: <BR>
154: If forRemove is true then the
155: object is being removed due to an explict remove request, in this case
156: the cache manager will have called this method regardless of the
157: state of the isDirty()
158:
159: <BR>
160: If an exception is thrown the object must be left in the clean state.
161:
162: <BR> MT - thread safe - Can be called at any time by the cache manager, it is the
163: responsibility of the object implementing Cacheable to ensure any users of the
164: object do not conflict with the clean call.
165:
166: @exception StandardException Standard Cloudscape error policy.
167:
168: */
169: public void clean(boolean forRemove) throws StandardException;
170: }
|