myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mmarinsc...@apache.org
Subject svn commit: r547126 - in /myfaces/orchestra/trunk/core/src/site: site.xml xdoc/about.xml xdoc/installation.xml xdoc/introduction.xml
Date Thu, 14 Jun 2007 05:27:16 GMT
Author: mmarinschek
Date: Wed Jun 13 22:27:15 2007
New Revision: 547126

URL: http://svn.apache.org/viewvc?view=rev&rev=547126
Log:
doc fixes

Added:
    myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml
      - copied, changed from r547114, myfaces/orchestra/trunk/core/src/site/xdoc/about.xml
Removed:
    myfaces/orchestra/trunk/core/src/site/xdoc/about.xml
Modified:
    myfaces/orchestra/trunk/core/src/site/site.xml
    myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml

Modified: myfaces/orchestra/trunk/core/src/site/site.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/site.xml?view=diff&rev=547126&r1=547125&r2=547126
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/site.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/site.xml Wed Jun 13 22:27:15 2007
@@ -35,7 +35,7 @@
 		</menu>
 
 		<menu name="MyFaces Orchestra">
-			<item name="About" href="about.html"/>
+			<item name="Introduction and Glossary" href="introduction.html"/>
 			<item name="Installation" href="installation.html"/>
 			<item name="Conversation API Usage" href="usage.html"/>
 			<item name="Best Practice" href="bestPractice.html"/>

Modified: myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml?view=diff&rev=547126&r1=547125&r2=547126
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml Wed Jun 13 22:27:15 2007
@@ -7,7 +7,7 @@
 	</properties>
 
 	<body>
-		<section name="Installation">Its assumed that you know how to setup
+		<section name="Installation">In the following, we will assume that you know how to
setup
 			<ul>
 				<li>a servlet container (Tomcat, Jetty, etc)</li>
 
@@ -15,12 +15,18 @@
 
 				<li>your JSF implementation (MyFaces, JSF-RI, etc)</li>
 			</ul>
-			<p>For a beginner these are serious assumptions, though, anything
-				else would have blast this guide.
-			</p>
-			The installation guide will show how
-			to setup a JPA entity manager, alter a chapter for Hibernate will be
-			added.
+			<p>For a beginner these are serious assumptions, however, anything
+				else would have made this guide way too long.
+            </p>
+			<p>
+                For an absolute beginner in using these technologies, we recommend taking
a look at the
+                <a href="http://code.google.com/p/facesgoodies/">Faces-Goodies</a>
project - a perfect way
+                of kickstarting you in the world of JSF, Spring and JPA and then return back
to include Apache
+                Orchestra.
+            </p>
+            The installation guide will show you how
+			to setup a JPA entity manager (so you are working with the new JavaPersistence API standard),
+            later a chapter explaining how to access Hibernate directly will be added.
 			<subsection name="Prerequisites">
 				<ul>
 					<li>Apache MyFaces Orchestra core</li>
@@ -37,23 +43,25 @@
 
 					<li>and all their dependencies
 						<br/>
-						I admit this is somehow vague, but
+						This might sound somehow vague, but
 						it depends on the JSF and JPA implementation. If you have to setup
-						this kind of thing from scratch it might be best to have a look at our
+						an application architecture like this from scratch it might be best to take a look
at our
 						examples package.
 					</li>
 				</ul>
 			</subsection>
 			<subsection name="Spring configuration">Apache MyFaces
-				Orchestra uses the powerful Spring configuration to provide its conversation
-				scope. In contrast to the JSF faces-config managed bean facility Spring
-				offers tremendous features, e.g. it allows us to create a new
+				Orchestra uses the powerful Spring framework to provide its conversation
 				scope.
+				Spring is - just like JSF managed-bean facility which is configured in the faces-config
files of
+				your application - a dependency injection framework.
+				Up and above the features of the managed-bean facility, Spring offers very nice additional
features;
+				essential for Apache Orchestra is that it allows us to create a new scope-type.
 				<p>Lets start with the Spring configuration for the conversation
-					scope and the JPA entity manager factory. This configuration file has to
+					scope and the JPA entity-manager factory. This configuration file has to
 					be placed into the WEB-INF directory of your web application using the
-					name applicationContext.xml. This can be configured, just have a look at
-					the Spring documentation.
+					name applicationContext.xml. This can be configured with a context-parameter in your
web.xml; for
+					more information, take a look at the Spring documentation.
 				</p>
 				<pre>
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;

Copied: myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml (from r547114, myfaces/orchestra/trunk/core/src/site/xdoc/about.xml)
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml?view=diff&rev=547126&p1=myfaces/orchestra/trunk/core/src/site/xdoc/about.xml&r1=547114&p2=myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml&r2=547126
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/about.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml Wed Jun 13 22:27:15 2007
@@ -20,9 +20,9 @@
 				your detached
 				objects back into the persistence session. Most of those problems, if not all, result
 				from the fact that a persistence session is opened and closed for each HTTP request.
-				The ORM tool has then no chance to manage your entities for the duration of a
-				business process - once you close a persistence session at the end of the HTTP request,
-				all entities are detached from the persistence session.
+				In this case, the ORM tool has no chance to manage your entities for the duration of
a
+				business process - once you close a persistence layer session at the end of the HTTP
request,
+				all entities are detached from the persistence layer session.
 			</p>
 			<p> So, the magic is to keep such a persistence session open
 				as long as required, but as short as possible; contrary to the often
@@ -40,10 +40,10 @@
 				the application ends the conversation.
 			</p>
 			<p>There is a lot of ambiguous wording in the area of persistence; before we start
we'll provide some definitions
-				so that we talk about the same things.
+				so that we talk about the same concepts in the same words.
 			</p>
 			<subsection
-				name="Definitions">
+				name="Glossary">
 				<ul>
 					<li>POJO
 						<br/>
@@ -123,7 +123,7 @@
 						keeps track of property updates and issues the database statements
 						required to synchronize the entity state with the database. If you
 						close an entity manager you will loose the coupling between its
-						internal state and your entities, they are so called "detached object"
+						internal state and your entities, they are so called "detached objects"
 						afterwards.
 					</li>
 
@@ -136,16 +136,19 @@
 
 					<li>DAO - Data Access Object
 						<br/>
-						Mostly a singleton which contains
-						all of the database requests your application will issue.
+						Usage of data access objects is based on the pattern with the same name. Data access
+                        objects are singletons which contain
+						all of the database requests your application will issue - generally, one data access
object
+                        encapsulates all database requests for one entity.
 						Thus, the DAO is injected with an entity
 						manager.
 					</li>
 
 					<li>Conversation
 						<br/>
-						A conversation is the bracket for all the
-						database operations required to finish a process.
+						A conversation is the time-span encapsulating all the
+						operations in your business logic required to finish a process
+                        (in the end, this will almost always include the need for executing
database transactions).
 						Other names of this principle are: application transaction, unit-of-work
 					</li>
 
@@ -153,13 +156,13 @@
 						<br/>
 						The session scope of your servlet container.
 						Beans put into this scope live until the configured inactivity timout
-						for the session has been reached.
+						for the session has been reached or the session is closed explicitly
 					</li>
 
 					<li>Request Scope
 						<br/>
 						The request scope of your servlet container.
-						The lifetime of those beans is as long as the duration of a
+						The lifetime of request-scoped-beans is as long as the duration of a
 						single HTTP request. Once the servlet container finishes sending
 						the page data, the request will die and with it all the beans put into
 						this scope.
@@ -177,7 +180,7 @@
 						<br/>
 						A backing bean is the bean behind a JSF view
 						(jsp, facelet, etc page). While JSF does not require such a bean, it is
-						good practice to do it that way.
+						good practice to provide one backing-bean per page as a rule of thumb.
 					</li>
 				</ul>
 			</subsection>
@@ -186,7 +189,7 @@
 				<ul>
 					<li>core
 						<br/>
-						The core is compatible with Java 1.4 - which means that you are
+						The core module is compatible with Java 1.4 - which means that you are
 						able to use all this convenient stuff without the need to migrate to
 						Java 5.0
 					</li>
@@ -194,11 +197,16 @@
 					<li>core15
 						<br/>
 						Ok, we admit, we couldn't resist, this package will contain
-						Java 5.0 enhancements to the core, so that you get some of the cool stuff as well.
+						Java 5.0 enhancements to the core, so that you get some of the cool new annotation
based
+                        stuff as well.
 					</li>
 
-					<li>examples</li>
-				</ul>
+					<li>examples
+                        <br/>
+						The examples module includes a demo app (one currently) showing off many of Orchestra's
+                        features.
+                    </li>
+                </ul>
 			</subsection>
 		</section>
 	</body>



Mime
View raw message