You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by di...@apache.org on 2001/09/11 12:35:26 UTC
cvs commit: xml-cocoon2/xdocs contrib.xml overview.xml
dims 01/09/11 03:35:26
Modified: . changes.xml
src/org/apache/cocoon/components/store MRUMemoryStore.java
StoreJanitorImpl.java
xdocs contrib.xml overview.xml
Log:
Docs and JavaDocs Patchs ONLY:
--------------------------------------------------------
- Patch for "changes.xml - entry for entity catalogs" from David Crossley <cr...@indexgeo.com.au>
- Patch for "xdocs/overview.xml - add section for Samples" from David Crossley <cr...@indexgeo.com.au>
- Patch for "xdocs/contrib.xml" from David Crossley <cr...@indexgeo.com.au>
- Patch for "javadoc update StoreJanitor/MRUMemoryStore" from "Gerhard Froehlich" <g-...@gmx.de>
Revision Changes Path
1.31 +5 -1 xml-cocoon2/changes.xml
Index: changes.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/changes.xml,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -r1.30 -r1.31
--- changes.xml 2001/08/22 12:03:32 1.30
+++ changes.xml 2001/09/11 10:35:26 1.31
@@ -4,7 +4,7 @@
<!--
History of Cocoon changes
- $Id: changes.xml,v 1.30 2001/08/22 12:03:32 sylvain Exp $
+ $Id: changes.xml,v 1.31 2001/09/11 10:35:26 dims Exp $
-->
<changes title="History of Changes">
@@ -58,6 +58,10 @@
<action dev="CZ" type="add">
Added patch by Stuart Roebuck (stuart.roebuck@adolos.com)
fixing the byte handling of the ImageDirectoryGenerator.
+ </action>
+ <action dev="DM" type="add">
+ Added capability to resolve external XML entities using an entity resolver.
+ See the documentation for "Entity Catalogs".
</action>
</release>
<release version="2.0b2" date="July 23, 2001">
1.19 +46 -37 xml-cocoon2/src/org/apache/cocoon/components/store/MRUMemoryStore.java
Index: MRUMemoryStore.java
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/org/apache/cocoon/components/store/MRUMemoryStore.java,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- MRUMemoryStore.java 2001/09/05 11:56:26 1.18
+++ MRUMemoryStore.java 2001/09/11 10:35:26 1.19
@@ -49,32 +49,13 @@
ThreadSafe, Runnable,
Composable, Contextualizable {
- /**
- * Indicates the daemon thread priority.
- */
+
private int priority;
-
- /**
- * Indicates the max. object in the cache
- */
private int maxobjects;
-
- /**
- * Sets the filesystem store on or off
- */
private boolean filesystem;
-
- /**
- * The heart of the cache
- */
private HashMap cache;
private LinkedList mrulist;
-
private Runtime jvm;
-
- /**
- * Filesystem storage;
- */
private File cachefile;
private Store fsstore;
private StoreJanitor storejanitor;
@@ -83,12 +64,12 @@
private File cachedir;
private File workdir;
private String cachedirstr;
-
- /** the component manager */
protected ComponentManager manager;
/**
- * Get the filesystem store from the component manager
+ * Get components of the ComponentManager
+ *
+ * @param the ComponentManager
*/
public void compose(ComponentManager manager) throws ComponentException {
try {
@@ -103,7 +84,9 @@
}
/**
- * Get the caching directory from the servlet context
+ * Get the context
+ *
+ * @param the Context of the application
*/
public void contextualize(Context context) throws ContextException {
this.cachedirstr = new String();
@@ -126,10 +109,13 @@
* Initialize the MRUMemoryStore.
* A few options can be used :
* <UL>
- * <LI>maxobjects = how many objects will be stored in memory (Default: 10o objects)</LI>
- * <LI>threadpriority = priority of the thread (1-10). (Default: 10)</LI>
+ * <LI>maxobjects = how many objects will be stored in memory (Default: 10 objects)</LI>
+ * <LI>threadpriority = priority of the threads (1-10). (Default: 10)</LI>
* <LI>filesystem = use filesystem storage to keep object persistent (Default: false)</LI>
* </UL>
+ *
+ * @param the Configuration of the application
+ * @exception ConfigurationException
*/
public void configure(Configuration conf) throws ConfigurationException {
this.jvm = Runtime.getRuntime();
@@ -161,10 +147,7 @@
}
/**
- * Background threads.
- * Thread checker checks that memory is not running too low in the JVM because of the Store.
- * It will try to keep overall memory usage below the requested levels.
- * Thread writer writes objects from the writer stack onto the filesystem.
+ * The writer thread writes objects from the writer stack onto the filesystem.
*/
public void run() {
while (true) {
@@ -192,15 +175,21 @@
* Store the given object in a persistent state. It is up to the
* caller to ensure that the key has a persistent state across
* different JVM executions.
+ *
+ * @param the key for the object to store
+ * @param the object to store
*/
public void store(Object key, Object value) {
this.hold(key,value);
}
/**
- * This method holds the requested object in a HashMap combined with a LinkedList to
- * create the MRU.
- * It also can store the objects onto the filesystem if configured.
+ * This method holds the requested object in a HashMap combined
+ * with a LinkedList to create the MRU.
+ * It also stores objects onto the filesystem if configured.
+ *
+ * @param the key of the object to be stored
+ * @param the object to be stored
*/
public void hold(Object key, Object value) {
getLogger().debug("Holding object in memory. key: " + key);
@@ -232,6 +221,9 @@
/**
* Get the object associated to the given unique key.
+ *
+ * @param the key of the requested object
+ * @return the requested object
*/
public Object get(Object key) {
getLogger().debug("Getting object from memory. Key: " + key);
@@ -270,8 +262,9 @@
}
/**
- * Remove the object associated to the given key and returns
- * the object associated to the given key or null if not found.
+ * Remove the object associated to the given key.
+ *
+ * @param the key of to be removed object
*/
public void remove(Object key) {
getLogger().debug("Removing object from store");
@@ -284,6 +277,9 @@
/**
* Indicates if the given key is associated to a contained object.
+ *
+ * @param the key of the object
+ * @return true if the key exists
*/
public boolean containsKey(Object key) {
synchronized(this.cache) {
@@ -292,7 +288,9 @@
}
/**
- * Returns the list of used keys as an Enumeration of Objects.
+ * Returns the list of used keys as an Enumeration.
+ *
+ * @return the enumeration of the cache
*/
public Enumeration keys() {
/* Not yet implemented */
@@ -301,7 +299,7 @@
/**
* Frees some of the fast memory used by this store.
- * It removes the last element in the cache.
+ * It removes the last element in the store.
*/
public void free() {
try {
@@ -320,6 +318,9 @@
* This method checks if an object is seriazable.
* FIXME: In the moment only CachedEventObject or
* CachedStreamObject are stored.
+ *
+ * @param the object to be checked
+ * @return true if the object is storeable
*/
private boolean checkSerializable(Object object) {
try {
@@ -337,6 +338,14 @@
}
}
+ /**
+ * This method puts together a filename for
+ * the object, which shall be stored on the
+ * filesystem.
+ *
+ * @param the key of the object
+ * @return the filename of the key
+ */
private String getFileName(String key)
{
return new StringBuffer()
1.3 +28 -6 xml-cocoon2/src/org/apache/cocoon/components/store/StoreJanitorImpl.java
Index: StoreJanitorImpl.java
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/org/apache/cocoon/components/store/StoreJanitorImpl.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- StoreJanitorImpl.java 2001/09/07 10:58:44 1.2
+++ StoreJanitorImpl.java 2001/09/11 10:35:26 1.3
@@ -48,6 +48,9 @@
* <LI>cleanupthreadinterval = how often (sec) shall run the cleanup thread</LI>
* <LI>threadpriority = priority of the thread (1-10). (Default: 10)</LI>
* </UL>
+ *
+ * @param the Configuration of the application
+ * @exception ConfigurationException
*/
public void configure(Configuration conf) throws ConfigurationException {
this.getLogger().debug("Configure StoreJanitorImpl");
@@ -59,6 +62,19 @@
this.setCleanupthreadinterval(params.getParameterAsInteger("cleanupthreadinterval",10));
this.setPriority(params.getParameterAsInteger("threadpriority",Thread.currentThread().getPriority()));
+ if ((this.getFreememory() < 1)) {
+ throw new ConfigurationException("StoreJanitorImpl freememory parameter has to be greater then 1");
+ }
+ if ((this.getHeapsize() < 1)) {
+ throw new ConfigurationException("StoreJanitorImpl heapsize parameter has to be greater then 1");
+ }
+ if ((this.getCleanupthreadinterval() < 1)) {
+ throw new ConfigurationException("StoreJanitorImpl cleanupthreadinterval parameter has to be greater then 1");
+ }
+ if ((this.getPriority() < 1)) {
+ throw new ConfigurationException("StoreJanitorImpl threadpriority has to be greater then 1");
+ }
+
this.setStoreList(new ArrayList());
Thread checker = new Thread(this);
@@ -69,6 +85,9 @@
checker.start();
}
+ /**
+ * The "checker" thread checks if memory is running low in the jvm.
+ */
public void run() {
while (true) {
// amount of memory used is greater then heapsize
@@ -94,7 +113,9 @@
}
/**
- * Method to check if memory is running low in the getJVM().
+ * Method to check if memory is running low in the JVM.
+ *
+ * @return true if memory is low
*/
private boolean memoryLow() {
this.getLogger().debug("getJVM().totalMemory()=" + this.getJVM().totalMemory());
@@ -105,7 +126,9 @@
}
/**
- * This method register the store in the StoreJanitor
+ * This method register the stores
+ *
+ * @param the store to be registered
*/
public void register(Store store) {
this.getLogger().debug("Registering store instance");
@@ -114,7 +137,9 @@
}
/**
- * This method unregister the store in the StoreJanitor
+ * This method unregister the stores
+ *
+ * @param the store to be unregistered
*/
public void unregister(Store store) {
this.getLogger().debug("Unregister store instance");
@@ -161,9 +186,6 @@
this.getJVM().gc();
}
- /**
- * Getter and setter methods
- */
private int getFreememory() {
return freememory;
}
1.7 +50 -17 xml-cocoon2/xdocs/contrib.xml
Index: contrib.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/xdocs/contrib.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- contrib.xml 2001/08/16 10:03:15 1.6
+++ contrib.xml 2001/09/11 10:35:26 1.7
@@ -82,7 +82,7 @@
there. (The @docname@ project does not maintain anything but the basic <code>.zip</code> and
<code>.tar.gz</code> packages, but anyone is welcome to build their own specific packages and
announce them on <code>cocoon-users</code>)</li>
- <li>... and there is just one other thing - don't forget to tell everyone who asks how great @doctitle@ is! ;-)
+ <li>... and there is just one other thing - don't forget to tell everyone who asks, how great @docname@ is! ;-)
The more people that know about and start to use @docname@, the larger the pool of
potential contributors there will be
- so, please, help us by placing the @docname@ logo somewhere in your
@@ -243,20 +243,20 @@
<p>
Every so often you should synchronise your local copy with the master
repository. Note that this definitely does not mean that your changes
- will be applied to the master. Exactly the opposite will happen - the
- remote master version is synchronised with yours. New items are
- automatically added to yours, and changed ones are refreshed. If someone
- else happened to have submitted patches for the same files while you were
- away, then changes will be merged with your copy and you will be warned
- of any conflicts. Easy and automatic ...
+ will be applied to the master. Exactly the opposite will happen - updates
+ from the remote master version are merged into your local repository.
+ New items are automatically added to yours, and changed ones are refreshed.
+ If someone else happened to have submitted patches for the same files while
+ you were away, then changes will be merged with your copy and you will be
+ warned of any conflicts. Easy and automatic ...
</p>
<ol>
<li><code>cd /usr/local/cvs</code></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login</code></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 \</code>
- <br/><code>update -r HEAD xml-cocoon2</code></li>
- <li>... pay attention to the update messages</li>
+ <br/><code>update -d -P -r HEAD xml-cocoon2</code></li>
+ <li><strong>... pay attention to the update messages</strong></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic logout</code></li>
</ol>
</s2>
@@ -266,8 +266,10 @@
<p>
To contribute your modifications, you need to produce a plain-text file
containing the differences between the master copy and yours. You will send
- this, along with an explanation of why it is required, to the authorised
- maintainers of the repository (via the procedures described below).
+ this, along with an explanation of why it is required, to the
+ <code>cocoon-dev</code> mailing list. One of the authorised
+ maintainers of the repository will review the patch and then apply it to the
+ relevant branch.
</p>
<p>
@@ -276,6 +278,8 @@
</p>
<ol>
+ <li>Make the desired changes in your local repository, build, test it
+ thoroughly</li>
<li><code>cd /usr/local/cvs/xml-cocoon2/xdocs</code></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login</code></li>
<li><code>cvs diff -u contrib.xml > $WORK/cocoon/contrib.xml.diff</code></li>
@@ -305,6 +309,13 @@
</p>
<p>
+ Most issues will be discovered, resolved, and then patched quickly
+ via the <code>cocoon-dev</code> mailing list. Larger issues, and ones that
+ are not yet fully understood or are hard to solve, are destined for
+ Bugzilla.
+ </p>
+
+ <p>
Experienced developers use Bugzilla directly, as they are very sure
when they have found a bug and when not. However, less experienced users
should first discuss it on the user or developer mailing list (as
@@ -325,8 +336,9 @@
it again until you get one. (But please not every hour - allow a few
days for the list to deal with it.) Do not be impatient - remember that
the whole world is busy, not just you. Bear in mind that other countries
- may have holidays at different times to your country. You might also
- consider re-writing your initial posting - perhaps it was not clear enough
+ will have holidays at different times to your country and that they are
+ in different time zones. You might also consider re-writing your initial
+ posting - perhaps it was not clear enough
and the readers' eyes glazed over.
</p>
</s1>
@@ -349,14 +361,20 @@
descriptive title.
</li>
<li>
+ Prepend your email subject line with <code>[Patch]</code>, or
+ <code>[Proposal]</code>, or something else, when that is appropriate.
+ </li>
+ <li>
When making changes to XML documentation, or any XML document for that
matter, use a
<link href="http://www.oasis-open.org/cover/">validating parser</link>
- (we use SP/nsgmls).
+ (one that is tried and true is
+ <link href="http://www.jclark/sp/">SP/nsgmls</link>).
This procedure will detect errors without having to go through the whole
<code>build docs</code> process to find them. Do not expect @docname@
or the build system to detect the validation errors for you - they can
- do it, but that is not their purpose.
+ do it, but that is not their purpose. (Anyway, nsgmls validation error
+ messages are more informative.)
</li>
<li>
Remember that most people are participating in development on a
@@ -376,9 +394,24 @@
Take the time to clearly explain your issue and write a concise email
message. Less confusion facilitates fast and complete resolution.
</li>
+ <li>
+ Do not bother to send an email reply that simply says "thanks".
+ When the issue is resolved, that is the finish - end of thread.
+ Reduce clutter.
+ </li>
+ <li>
+ You would usually do any development work against the HEAD branch of CVS.
+ </li>
+ <li>
+ When sending a patch, you usually do not need to worry about which CVS
+ branch it should be applied to. The maintainers of the repository will
+ decide.
+ </li>
<li>
- Do not send an email reply that simply says "thanks". When the issue is
- resolved, that is the finish - end of thread. Reduce clutter.
+ If an issue starts to get bogged down in list discussion, then it may
+ be appropriate to go into private off-list discussion with a few interested
+ other people. Spare the list from the gory details. Report a summary back
+ to the list to finalise the thread.
</li>
<li>
Become familiar with the mailing lists. As you browse and search, you will
1.3 +30 -6 xml-cocoon2/xdocs/overview.xml
Index: overview.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/xdocs/overview.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- overview.xml 2001/07/19 14:20:23 1.2
+++ overview.xml 2001/09/11 10:35:26 1.3
@@ -3,7 +3,7 @@
<document>
<header>
<title>Overview of @doctitle@</title>
- <version>0.1</version>
+ <version>0.2</version>
<type>Overview document</type>
<authors><person name="Tom Klaasen" email="tom.klaasen@the-ecorp.com"/>
</authors>
@@ -13,12 +13,36 @@
<p>@docname@ is an XML publishing framework. It allows you to define XML
documents and transformations to be applied on it, to eventually generate a
presentation format of your choice (HTML, PDF, SVG, ...).</p>
- <p>@docname@ also gives you the possibility to have logic in your XML files
- (so that the XML file itself can become dynamically generated).</p>
+ <p>@docname@ also gives you the possibility to apply logic to your XML files
+ (so that the XML pipeline can be dynamic).</p>
</s1>
- <s1 title="General structure">
- <p>This section gives a general overview of how an XML document is
- handled by @docname@.</p>
+
+ <anchor id="samples"/>
+ <s1 title="Examples and demonstration applications">
+ <p>
+ There are a whole suite of sample applications to demonstrate the power
+ of @docname@. These samples are available from the "welcome" page after
+ you have downloaded, built, and installed the distribution.
+ Each example portrays a different aspect of the vast capabilities of
+ @docname@.
+ </p>
+
+ <p>
+ It will greatly assist your understanding of @docname@ to investigate
+ behind-the-scenes, to find out how each sample is processed. Do this
+ by looking at the actual XML documents provided in the distribution at
+ <code>webapp/docs/samples/</code> and by consulting the sitemap to see
+ the processing steps that are defined.
+ </p>
+ </s1>
+
+ <s1 title="Overview of XML document processing">
+ <p>This section gives a general overview of how an XML document is
+ handled by @docname@. See also the document
+ <link href="uc2.html">Understanding @docname@</link> for explanation of
+ the separation of content, style, logic and management functions.
+ </p>
+
<s2 title="Pipeline">
<p>@docname@ relies on the pipeline model: an XML document is pushed
through a pipeline, that exists in several transformation steps of your
----------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org