db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arm...@apache.org
Subject cvs commit: db-ojb/xdocs objectcache.xml
Date Wed, 09 Apr 2003 09:28:52 GMT
arminw      2003/04/09 02:28:52

  Modified:    xdocs    objectcache.xml
  Log:
  format and update documentation
  
  Revision  Changes    Path
  1.3       +123 -72   db-ojb/xdocs/objectcache.xml
  
  Index: objectcache.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/xdocs/objectcache.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- objectcache.xml	20 Jul 2002 06:13:29 -0000	1.2
  +++ objectcache.xml	9 Apr 2003 09:28:52 -0000	1.3
  @@ -1,27 +1,50 @@
  -<?xml version="1.0"?>
  +<?xml version="1.0" encoding="ISO-8859-1"?>
   <document>
   
     <properties>
       <author email="thma@apache.org">Thomas Mahler</author>
  +    <author>Armin Waibel</author>
       <title>ObJectRelationalBridge Features</title>
     </properties>
   
   <body>
   
  -<section name="the ojb object cache">
  +<section name="Object cache">
   
  -<H2><FONT FACE="Times, serif">why a cache</FONT></H2>
  -<P><FONT FACE="Times, serif">OJB provides a simple Object Cache that
  +<ul>
  +    <li><a href="#why cache">Why a cache?</a></li>
  +    <li><a href="#how works">How it works</a></li>
  +    <li><a href="#alternative">Alternative cache implementations</a></li>
  +    <li><a href="#implement cache">Implement your own cache</a></li>
  +    <li><a href="#"></a></li>
  +    <li><a href="#cache filter">CacheFilter feature</a>
  +        <ul>
  +            <li><a href="#what means">What does cache filtering mean</a></li>
  +            <li><a href="#default filter">Default CacheFilter implementations</a></li>
  +            <li><a href="#implement filter">Implement your own filter</a></li>
  +        </ul>
  +    </li>
  +</ul>
  +<p>
  +All classes belonging to the <code>Object Cache</code> part of OJB you will
find under the
  +<code>org.apache.ojb.broker.cache</code>-package.
  +</p>
  +
  +
  +
  +<subsection name="Why a cache?" anchor="why cache">
  +<p>
  +OJB provides a pluggable Object Cache that
   holds Objects previously loaded or stored by the PersistenceBroker.
  -Using a Cache has several advantages:</FONT></P>
  -<UL>
  -    <li>it increases performance as it reduces <FONT FACE="Times, serif">database</FONT>
  -    lookups. <FONT FACE="Times, serif">If an object is looked up by the
  -    PersistenceBroker, it does not perform a SELECT against the database
  -    <FONT FACE="Times, serif">immediately </FONT>but first looks up the
  +Using a Cache has several advantages:
  +<ul>
  +    <li>it increases performance as it reduces database
  +    lookups. If an object is looked up by the
  +    PersistenceBroker, it does not perform a <code>SELECT</code> against the
database
  +    immediately but first looks up the
       cache if the requested object is already loaded. If the object is
       cached it is returned as the lookup result. If it is not cached a
  -    SELECT is performed.</FONT>
  +    <code>SELECT</code> is performed.
       </li>
       <li>it maintains the uniqueness of objects. If several queries
       ask for an object with the same Identity (OID) they will receive one
  @@ -33,94 +56,122 @@
       objects) that would result in non-terminating loops without such a
       cache.
       </li>
  -</UL>
  -<H2>how it works</H2>
  -<P>The OJB Cache provides the following interface to allow caching,
  -lookup and removal of objects:</P>
  -<PRE>package ojb.broker.accesslayer;
  +</ul>
  +</p>
  +</subsection>
  +
  +
  +
  +<subsection name="How it works" anchor="how works">
  +<p>
  +The OJB Cache provides the following interface to allow caching,
  +lookup and removal of objects:
  +<source>
   public interface ObjectCache
   {
       /**
  -     * Make object obj persistent to Objectcache.
  -     * compute objects identity and use it as key for the hashmap
  -     */
  -    public void cache(Object obj) throws ClassNotPersistenceCapableException;
  -
  -    /**
  -     * makes object obj persistent to the Objectcache under the key oid.
  +     * makes object obj persistent to the Objectcache
  +     * under the key oid.
        */
       public void cache(Identity oid, Object obj);
   
  +
       /**
        * Lookup object with Identity oid in objectTable.
        * returns null if no matching id is found
        */
       public Object lookup(Identity oid);
   
  +
       /**
        * removes an Object from the cache.
  +     * @param obj the Object (or the Identity of the object)
  +     * to be removed.
        */
  -    public void remove(Object obj);
  +    public void remove(Identity oid);
   
       /**
        * clear the ObjectCache.
        */
       public void clear();
  -}</PRE><P>
  -The OJB default implementation resides in the class
  -ojb.broker.accesslayer.ObjectCacheDefaultImpl. This implementation
  -uses a hashtable to hold all cached objects:</P>
  -<PRE>   private Hashtable objectTable = new Hashtable();</PRE><P>
  -The Hashtable uses Identities as keys and object-references as
  -values. For an example see the code of the <FONT FACE="Courier, monospace">.cache(...)
  -</FONT>method:</P>
  -<PRE>   public void cache(Identity oid, Object obj)
  -   {
  -        if (obj != null)
  -        {
  -            SoftReference ref = new SoftReference(obj);
  -            objectTable.put(oid.toString(), ref);
  -        }
  -   }</PRE><P>
  +}
  +</source>
  +The OJB default <code>ObjectCache</code> implementation resides in the class
  +<code>ojb.broker.accesslayer.ObjectCacheDefaultImpl</code>. This implementation
  +uses a static hashtable to hold all cached objects:
  +<source>
  +...
  +public void cache(Identity oid, Object obj)
  +{
  +    if ((obj != null))
  +    {
  +        SoftReference ref = new SoftReference(obj);
  +        objectTable.put(oid.toString(), ref);
  +    }
  +}
  +...
  +</source>
   As you will have noticed, OJB uses SoftReferences. A SoftReference is
   not treated as a ordinary java reference. That is: if an object is
   not longer referenced by your application but only by the cache it
   can be reclaimed by the garbage collector (gc). The OJB cache does
   not provide its own memory management but lets the JVM gc do the job.
  -Thus the lookup method has to take care if the gc did reclaim
  -objects:</P>
  -<PRE>    public Object lookup(Identity oid)
  -    {
  -        Object obj = null;
  -        SoftReference ref = (SoftReference) objectTable.get(oid.toString());
  -        if (ref != null)
  -        {
  -            obj = ref.get();
  -            if (obj == null) // Soft-referenced Object reclaimed by GC !
  -            {
  -                objectTable.remove(oid);
  -            }
  -        }
  -        return obj;
  -    }</PRE><P>
  -<br/><br/>
  -</P>
  -<H2>implement your own cache</H2>
  -<P>The OJB cache is quite simple but does a good job for most
  +</p>
  +</subsection>
  +
  +
  +
  +
  +<subsection name="Alternative cache implementations" anchor="alternative" >
  +<p>
  +TODO
  +</p>
  +</subsection>
  +
  +
  +
  +<subsection name="Implement your own cache" anchor="implement own">
  +<p>
  +The OJB cache is quite simple but does a good job for most
   scenarios. If you need a more sophisticated cache (e.g. with MRU
   memory management strategies) you'll write your own implementation of
  -the interface <FONT FACE="Courier, monospace">ojb.broker.accesslayer.ObjectCache</FONT>.
  -OJB provides a simple mechanism to integrate your implementation:</P>
  -<P>OJB obtains its cache instance from the factory
  -<FONT FACE="Courier, monospace">ojb.broker.accesslayer.ObjectCacheFactory</FONT>.
  -This Factory can be configured to generate instances of your specific
  -implementation by changing the following entry in the configuration
  -file OJB.properties:</P>
  -<P STYLE="margin-bottom: 0cm"><FONT FACE="Courier, monospace">ObjectCacheClass=ojb.broker.accesslayer.ObjectCacheDefaultImpl</FONT></P>
  -<P STYLE="margin-bottom: 0cm">to:</P>
  -<P STYLE="margin-bottom: 0cm"><FONT FACE="Courier, monospace">ObjectCacheClass=acme.com.MyOwnObjectCache.</FONT></P>
  -<P>Of course I'm interested in your solutions! If you have
  -implemented something interesting, just contact me.</P>
  +the interface <code>ojb.broker.cache.ObjectCache</code>.
  +<br/>
  +Integration of your implementation in OJB is easy since the object cache is
  +a pluggable component. All you have to do, is to declare it in the
  +<code>OJB.properties</code> file by setting the <code>ObjectCacheClass</code>
  +property:
  +<source>
  +ObjectCacheClass=org.apache.ojb.broker.cache.ObjectCacheMyOwnImpl
  +</source>
  +</p>
  +
  +<p>Of course I'm interested in your solutions! If you have
  +implemented something interesting, just contact me.</p>
  +</subsection>
  +
  +
  +
  +
  +<subsection name="CacheFilter feature" anchor="cache filter">
  +
  +<a name="what means"/><b>What does cache filtering mean</b><br/>
  +<p>
  +TODO
  +</p>
  +
  +<a name="default filter"/><b>Default CacheFilter implementations</b><br/>
  +<p>
  +TODO
  +</p>
  +
  +<a name="implement filter"/><b>Implement your own filter</b><br/>
  +<p>
  +TODO
  +</p>
  +
  +</subsection>
  +
   
   </section>
   
  
  
  

Mime
View raw message