01: /*
02:
03: Derby - Class org.apache.derby.iapi.services.cache.CacheableFactory
04:
05: Licensed to the Apache Software Foundation (ASF) under one or more
06: contributor license agreements. See the NOTICE file distributed with
07: this work for additional information regarding copyright ownership.
08: The ASF licenses this file to you under the Apache License, Version 2.0
09: (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: /**
25: Any object that implements this interface can be cached using the services of
26: the CacheManager/CacheFactory. In addition to implementing this interface the
27: class must be public and it must have a public no-arg constructor. This is because
28: the cache manager will construct objects itself and then set their identity
29: by calling the setIdentity method.
30: <P>
31: A Cacheable object has five states:
32: <OL>
33: <OL>
34: <LI> No identity - The object is only accessable by the cache manager
35: <LI> Identity, clean, unkept - The object has an identity, is clean but is only accessable by the cache manager
36: <LI> Identity, clean, kept - The object has an identity, is clean, and is in use by one or more threads
37: <LI> Identity, kept, dirty - The object has an identity, is dirty, and is in use by one or more threads
38: <LI> Identity, unkept, dirty - The object has an identity, is dirty but is only accessable by the cache manager
39: </OL>
40: </OL>
41: <BR>
42: While the object is kept it is guaranteed
43: not to change identity. While it is unkept no-one outside of the
44: cache manager can have a reference to the object.
45: The cache manager returns kept objects and they return to the unkept state
46: when all the current users of the object have released it.
47: <BR>
48: It is required that the object can only move into a dirty state while it is kept.
49:
50: <BR> MT - Mutable : thread aware - Calls to Cacheable method must only be made by the
51: cache manager or the object itself.
52:
53: @see CacheManager
54: @see CacheFactory
55: @see Class#newInstance
56: */
57: public interface CacheableFactory {
58:
59: public Cacheable newCacheable(CacheManager cm);
60: }
|