commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bali...@apache.org
Subject cvs commit: jakarta-commons-sandbox/simplestore/docs users-guide.html
Date Sun, 31 Mar 2002 22:13:50 GMT
baliuka     02/03/31 14:13:50

  Modified:    simplestore/docs users-guide.html
  Log:
  
  
  Revision  Changes    Path
  1.4       +140 -149  jakarta-commons-sandbox/simplestore/docs/users-guide.html
  
  Index: users-guide.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/simplestore/docs/users-guide.html,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- users-guide.html	31 Mar 2002 17:34:03 -0000	1.3
  +++ users-guide.html	31 Mar 2002 22:13:50 -0000	1.4
  @@ -1,74 +1,70 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  +<html>
  +<head>
   
  -<HTML>
  -  <HEAD>
  -  <STYLE>
  -    h3{ color:navy };
  -    code{ color:navy };
  -  </STYLE>
  -    <TITLE>SimpleStore Usere Guide</TITLE>
  -  </HEAD>
  -  <BODY alink='navy' vlink='navy' >
  -     <center><h3>SimpleStore Users Guide</h3></center>
  - <h3>What is SimpleStore ?</h3>
  -  <p> 
  -
  -    SimpleStore is customizable persistence framework. It defines
  -    interfaces for Transparent Persistence and provides reference implementation.
  -    It designed to store objects in Transactional resource like RDMS, but
  -    can be used with any kind of storage. It is two storage types
  -    in reference implementation: RDMS and <a href='http://jdbm.sourceforge.net'>BTree
file from JDBM</a>.
  -    
  -
  -  </p>
  - <h3 > What can SimpleStore do for me ?</h3>
  - <p>
  -
  -   You can use it to implement persistence aspect in your web application, or
  -   object model, you can use it as  service for you server like  
  -     <a href='http://eob.sourceforge.net'>EOB</a> or EJB (CMP,BMP). 
  -   You can extend it and implement your  persitence framework or for some like JDO. 
  -  SimpleStore is Open Source and you can use it in commercial projects, see
  -  Apache <a href='http://www.apache.org/foundation/licence-FAQ.html'> license </a>
for details.
  +<title>SimpleStore Usere Guide</title>
  +  <style>
  +   h3{color:navy};
  +   pre{color:navy};
  +   code{color:navy};
      
  - </p>
  -
  - <h3> PersitenceManagerFactory </h3>
  +  </style>
  +</head>
  +<body  link='navy' alink='navy' vlink='navy'>
   
  -  <p>
  -    This interface is used to implement well known Factory design pattern it
  -    used to setup singleton <code>PersitenceManager</code> instanse. <code>PersitenceManager</code>
is
  -    the most specific interface in your code:
  -   <p>
  -   <code>
  -     <pre >
  +<center><h2 style='color:navy'> SimpleStore Users Guide</h2></center>
  + <h3>What is SimpleStore ?</h3>
  +<p>
  + SimpleStore is customizable persistence framework. 
  + It defines interfaces for Transparent Persistence and provides reference implementation.
  + It designed to store objects in Transactional resource like RDMS, but can be used with
any kind of storage. 
  + It is two storage types in reference implementation: 
  + RDMS and <a href='http://jdbm.sourceforge.org'>BTree file from JDBM project</a>.
&quot;Transparent&quot; means no Query Language,
  + Code Generation or Storage Specific API. Persistent Object doe's not extend any specific

  + class and doe's not implement some interface from SimpleStore API. Users code can use
it,
  + but must not depend on it( Downcast ). It is recommended to &quot;hide&quot; PersistentManager
  + and internal Transactions too. Use Facade and Factory design patterns to make your code
clean. 
  + It is useful if you will decide to make your objects Distributed. 
  + See Apache's AltRMI for more information on Transparent Distribution implementation. 
  +</p>
  +<h3>What can SimpleStore do for me ?</h3>
  +<p>
  + You can use it to implement persistency aspect in your web application,
  + or object model, you can use it as service for your server like 
  + <a href='http://eob.sourceforge.org'>EOB</a> or EJB (CMP,BMP).
  + You can extend it and implement your persistence framework or for some like JDO.
  + SimpleStore is Open Source and you can use it in commercial projects, see Apache 
  +  <a href='http://www.apache.org/foundation/licence-FAQ.htm'> license </a>
for details. 
  +</p>
  +<h3>PersitenceManagerFactory</h3>
  +<p>
  +This interface is used to implement well known Factory design pattern it used to setup
singleton 
  +<code>PersitenceManager</code> instanse.<code>PersitenceManager</code>
is the most specific 
  +interface in your code: 
  +<pre>
        DBPersistenceManagerFactory factory = new DBPersistenceManagerFactory();
  -        factory.setDriver(<span style='color:red'>"org.hsqldb.jdbcDriver"</span>);
  -        factory.setUrl(<span style='color:red'>"jdbc:hsqldb:sample"</span>);
  -        factory.setUser(<span style='color:red'>"sa"</span>);
  -        factory.setPassword(<span style='color:red'>""</span>);
  -        factory.setMaxConnections(<b style='color:blue'>1</b>);
  -        factory.setMetaResource(<span style='color:red'>"org/apache/commons/simplestore/storage.xml"</span>);
  +        factory.setDriver(<span style='color:red'>&quot;org.hsqldb.jdbcDriver&quot;</span>);
  +        factory.setUrl(<span style='color:red'>&quot;jdbc:hsqldb:sample&quot;</span>);
  +        factory.setUser(<span style='color:red'>&quot;sa&quot;</span>);
  +        factory.setPassword(<span style='color:red'>&quot;&quot;</span>);
  +        factory.setMaxConnections(<b>1</b>);
  +        factory.setMetaResource(<span style='color:red'>&quot;org/apache/commons/simplestore/storage.xml&quot;</span>);
         PersitenceManager  pm = factory.<b>getPersistenceManager</b>();
  -    </pre>
  -   </code> 
  -   this example setups PersitenceManager to use RDMS as storage.
  -  </content>
  -   <h3 >PersitenceManager</h3>
  -   <p>
  -    <code>PersitenceManager</code> is factory for you beans and transactions,
<code>Transaction</code> is
  -    the last interface you need to know from SimpleStore if you not going to extend
  -    SimpleStore. You dont need to exdend any specific Class or implement internal
  -    persitence interfaces, you dont need any code generator. Just design your
  -    object model, use interfaces and classes, SimpleStore will implement persitence
  -    aspect for you, but you still need some "Metadata" it very trivial xml file, but 
  -    it can be writen usin opional tags or generated later. Start to desin beans:
  -   </p>
  -     <code>
  -   <pre >
  - <b>public abstract class</b> Message 
  -   
  -  {
  +</pre>
  +
  +this example setups <code>PersitenceManager</code> to use RDMS as storage.
 
  +</p>
  +<h3>PersitenceManager</h3>
  +<p>
  +<code>PersitenceManager</code> is factory for your beans and transactions,
<code>Transaction</code> is the 
  + last interface you need to know from SimpleStore if you not going to extend SimpleStore.

  + You don't need to extend any specific Class or implement internal persistence interfaces,
y
  + ou don't need any code generator. Just design your object model, use interfaces and classes,

  + SimpleStore will implement persistence aspect for you, but you still need some &quot;Metadata&quot;

  + it is very trivial xml file, but it can be written using optional tags or 
  + generated later. Start to design beans: 
  +<pre>
  + <b>public abstract class</b> Message{
  +
           public MessageImpl(){}
   
           public void addReply(Message m) {
  @@ -80,7 +76,7 @@
       }
        <b>public abstract</b> java.util.Collection <b>getReplies</b>();
   
  -     <b>public abstract</b> Date <b>getSubmitted</b>(); 
  +     <b>public abstract</b> Date <b>getSubmitted</b>();
   
        <b>public abstract</b> void <b>setSubmitted</b>(Date v);
   
  @@ -88,7 +84,7 @@
   
        <b>public abstract</b> void <b>setContents</b>(String v);

   
  -     <b>public abstract</b> String <b>getEmail</b>(); 
  +     <b>public abstract</b> String <b>getEmail</b>();
   
        <b>public abstract</b> void <b>setEmail</b>(String v); 
   
  @@ -99,22 +95,18 @@
        <b>public abstract</b> String <b>getSubject</b>(); 
   
        <b>public abstract</b> void <b>setSubject</b>(String v);
  -    
  -     <b>public abstract</b> void <b>setParent</b>( Message parent
) ;
   
  -    
  +     <b>public abstract</b> void <b>setParent</b>( Message parent
);
  +
      }
  -    </pre> 
  -     </code>
  -   <p>
  -    This is persistent bean from Jakarta Velocity demo. All abstract methods are implemented

  -    by SimpleStore, <code>PersitenceManager</code> returns this implementation
:
  -   </p>
  -    <code>
  -     <pre >
  + </pre>
  + This is persistent bean from <a href='http://jakarta.apache.org/velocity'> Jakarta
Velocity </a> demo, it is recommended framework for web applications. 
  +All abstract methods are implemented by SimpleStore, <code>PersitenceManager</code>

  +returns this implementation:
  +<pre>
          PersitenceManager  pm = factory.<b>getPersistenceManager</b>();
          Transaction transaction = pm.<b>getTransaction</b>(); 
  -       
  +
          transaction.<b>begin</b>();   
   
             Message parent = pm.<b>findInstance</b>(Message.class,parentOid);
  @@ -126,83 +118,82 @@
                     parent.addReplay(msg);
   
          transaction.<b>commit</b>();
  -    </pre> 
  -    </code>
  -  Last you will need some metadata it helps simplestore to implement your beans:
  - <code>
  -  <pre>
  -     
  -   &lt;?xml version="1.0" encoding="UTF-8" ?&gt; 
  + </pre>
  +At last you will need some metadata it helps simplestore to implement your beans: 
  + <pre>
  +   &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?&gt;

       &lt;!DOCTYPE storage&gt; 
         &lt;storage&gt;
  -        &lt;mclass  id="<b>Message</b>" name="MESSAGE"&gt;
  -          &lt;field id="<b>parent</b>" name="parent"&gt;
  -              &lt;reference mclass="<b>Message</b>"/&gt; 
  +        &lt;mclass  id=&quot;Message&quot; name=&quot;MESSAGE&quot;&gt;
  +          &lt;field id=&quot;<b>parent</b>&quot; name=&quot;parent&quot;&gt;
  +              &lt;reference mclass=&quot;<b>Message</b>&quot;/&gt;
             &lt;/field&gt;
  -          &lt;field id="<b>replies</b>"&gt;
  -          &lt;reference mclass="<b>Message</b>" field="parent"/&gt;

  +          &lt;field id=&quot;<b>replies</b>&quot;&gt;
  +          &lt;reference mclass=&quot;<b>Message</b>&quot; field=&quot;parent&quot;/&gt;

             &lt;/field&gt;
           &lt;/mclass&gt;
        &lt;/storage&gt;
  -  
  -</pre>
  - </code>
  - <h3 >Transaction</h3>
  -    <p>
  -    SimpleStore supports only atomic persistence operations,
  -    All operations must be in transaction context:
  -   <code>
  -   <pre> 
  +  </pre>
  +</p>
  +<h3>Transaction</h3>
  +<p>
  +SimpleStore supports only atomic persistence operations, All operations must be in transaction
context: 
  + <pre>
       Transaction transaction = pm.<b>getTransaction</b>(); 
  -        transaction.<b>begin</b>();   
  -           
  +        transaction.<b>begin</b>();
           //..........................
           //    <i> operations </i>
           //..........................
  -    
  -        transaction.<b>commit</b>();// or transaction.<b>rollback</b>();
  -    
  -    
  -    </pre>
  -    </code>
  -    </p>  
  -    <h3>Identity</h3>  
  -    All persistent objects have OID, it is recomended to use Serializable Object for OID,
  -    reference implementaion uses <code>java.lang.Long</code> and default (Random)
generator.
  -    It is single persistent instance in SimpleStore with concreate OID.
  -   <pre>
  -   <code>
  +       transaction.<b>commit</b>();// or transaction.<b>rollback</b>();
  + </pre>  
  + </p>
  +<h3>Identity</h3>
  +<p>
  +All persistent objects have OID, it is recomended to use <code>Serializable</code>
Object for OID,
  + reference implementaion uses java.lang.Long and default (Random) generator. 
  +It is single persistent instance in SimpleStore with concreate OID. 
  +<pre>
       PersistenceManager.getOID(object1).
  -                    equals(PersistenceManager.getOID(object2) );
  -      </code><h4><strong>&lt;==&gt;</strong></h4>
  -    <code>object1 <b>==</b> object2;</code>
  -    </code><h4><strong>&lt;==&gt;</strong></h4>
  -    <code>object1.equals(object2);</code>
  -  
  -   </pre>
  -  OID is managed by framework and it is no way to change it for persistent object.
  -  SimpleStore overrides <code>int hashCode()</code> and 
  - <code>boolean equals(Object obj)</code>  methods in class Object.
  - <h3>State</h3>   
  -  It is to methods in <code>PersistenceManager</code> for persitent object
state.
  -  <code>boolean isNew(Object p)</code> returns <code>true</code>
if object is
  -  returned from <code>Object createInstance(Class cls)</code> in current transaction.
  -  <code>boolean isDeleted(Object p)</code> returns <code>true</code>
if object is
  -  deleted in any transacton. Use <code>void removeInstance(Object p)</code>
to
  -  delete persistent object. Managed methods throws 
  -  <code>java.lang.IllegalStateException</code> if deleted
  -  object is accessed inside or outside transaction.
  - <h3>Cashe</h3>   
  -  Cache is transparent for SimpleStore user. It used for optimizations and reachability
  -  management, but it is "invisible" in code.
  - <h3>Validation</h3>
  -  Metadada is used to define validation rules. Validator is custom object see
  -  javadoc for more information on <code>Validator</code> interface. Persistent
  -  object implementation throws ValidationException if registread validator returns
  -   false for managed property value.
  - <h3>Security</h3>
  -  Custom interceptors used for security checks. SimpleStore doe's not define
  -  any specific Permissions. Read more about customizations in 
  -  <a href='developers-guide.html'>Developers Guide</a> 
  - </BODY>
  -</HTML>
  +                    <b>equals</b>(PersistenceManager.<b>getOID</b>(object2)
);
  +     <h4> &lt;==&gt; </h4>
  +       object1 <b>==</b> object2;
  +     <h4> &lt;==&gt; </h4>
  +     object1.<b>equals</b>(object2);
  +</pre>
  +OID is managed by framework and it is no way to change it for persistent object. 
  +SimpleStore overrides <code>int hashCode()</code> and <code>boolean equals(Object
obj)</code>
  + methods in class Object. 
  +</p>
  +<h3>State</h3>
  +<p>
  +It is to methods in PersistenceManager for persitent object state.
  +<code> boolean isNew(Object p)</code> returns <code>true</code>
if object is returned from 
  +<code>Object createInstance(Class cls)</code> in current transaction. 
  +<code>boolean isDeleted(Object p)</code> returns 
  +<code>true</code> if object is deleted in any transacton. Use void <code>removeInstance(Object
p)</code>
  + to delete persistent object. Managed methods throws 
  + <code>java.lang.IllegalStateException</code>
  + if deleted object is accessed inside or outside transaction. 
  +</p>
  +<h3>Cashe</h3>
  +<p>
  +Cache is transparent for SimpleStore user. It used for optimizations and 
  +reachability management, but it is &quot;invisible&quot; in code. 
  +It is recomended to use default implementation. 
  +</p>
  +<h3>Validation</h3>
  +<p>
  +Metadada is used to define validation rules.
  + <code>Validator</code> is custom object see javadoc for more information on

  +<code>Validator</code> interface, 
  +and sample <code>NotNull</code> validator implementation. Persistent object
implementation throws 
  +<code>ValidationException</code> if registread validator returns false for
managed property value. 
  +</p>
  +<h3>Security</h3>
  +<p>
  +Custom interceptors used for security checks. 
  +SimpleStore doe's not define any specific Permissions and doe's no security checks. 
  +Read more about customizations in Developers Guide. 
  +</p>
  +</body>
  +</html>
  \ No newline at end of file
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message