You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ba...@apache.org on 2002/04/01 00:13:50 UTC
cvs commit: jakarta-commons-sandbox/simplestore/docs users-guide.html
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>. "Transparent" 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 "hide" 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'>"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>1</b>);
+ factory.setMetaResource(<span style='color:red'>"org/apache/commons/simplestore/storage.xml"</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 "Metadata"
+ 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>
-
- <?xml version="1.0" encoding="UTF-8" ?>
+ </pre>
+At last you will need some metadata it helps simplestore to implement your beans:
+ <pre>
+ <?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE storage>
<storage>
- <mclass id="<b>Message</b>" name="MESSAGE">
- <field id="<b>parent</b>" name="parent">
- <reference mclass="<b>Message</b>"/>
+ <mclass id="Message" name="MESSAGE">
+ <field id="<b>parent</b>" name="parent">
+ <reference mclass="<b>Message</b>"/>
</field>
- <field id="<b>replies</b>">
- <reference mclass="<b>Message</b>" field="parent"/>
+ <field id="<b>replies</b>">
+ <reference mclass="<b>Message</b>" field="parent"/>
</field>
</mclass>
</storage>
-
-</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><==></strong></h4>
- <code>object1 <b>==</b> object2;</code>
- </code><h4><strong><==></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> <==> </h4>
+ object1 <b>==</b> object2;
+ <h4> <==> </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 "invisible" 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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>