cziegeler 01/10/05 00:27:46
Modified: documentation/xdocs catalog.xml
src/org/apache/cocoon/components/resolver ResolverImpl.java
webapp cocoon.xconf
Log:
[Patch] entity catalogs: accept parameters from xconf
Submitted by: David Crossley [[EMAIL PROTECTED]]
Revision Changes Path
1.2 +107 -57 xml-cocoon2/documentation/xdocs/catalog.xml
Index: catalog.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/documentation/xdocs/catalog.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- catalog.xml 2001/09/28 13:41:28 1.1
+++ catalog.xml 2001/10/05 07:27:46 1.2
@@ -5,7 +5,7 @@
<header>
<title>Entity resolution with catalogs</title>
<subtitle>Resolve external entities to local or other resources</subtitle>
- <version>1.4</version>
+ <version>1.5</version>
<type>Technical document</type>
<authors>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
@@ -53,7 +53,7 @@
</p>
<p>
- With powerful catalog support there are no such problems. This document
+ With the powerful catalog support there are no such problems. This document
provides the following sections to explain @docname@ capability for
resolving entities ...
</p>
@@ -77,9 +77,8 @@
and shows catalogs in action
</li>
<li>
- <link href="#imp">Implementation and default configuration</link>
- - describes how support for catalogs is added to @docname@ and
- explains the default automated configuration
+ <link href="#default">Default configuration</link>
+ - explains the default automated configuration
</li>
<li>
<link href="#config">Local configuration</link>
@@ -87,6 +86,10 @@
system requirements and provides an example
</li>
<li>
+ <link href="#imp">Implementation notes</link>
+ - describes how support for catalogs is added to @docname@
+ </li>
+ <li>
<link href="#dev">Development notes</link>
- some minor issues need to be addressed
</li>
@@ -255,9 +258,17 @@
System identifiers can use full pathnames, filenames, relative pathnames,
or URLs - in fact, any method that will define and deliver the actual
physical entity. If it is just a filename or a relative pathname, then the
- entity resolver will look for the resource relative to the location of
+ Catalog Resolver will look for the resource relative to the location of
the catalog.
</p>
+
+ <p>
+ When the parser needs to load a declared entity, then it first consults
+ the Catalog Resolver to get a possible mapping to an alternate system
+ identifier. If there is no mapping for an identifier in the catalogs
+ (or in any sub-ordinate catalogs), then @docname@ will carry on to
+ retrieve the resource using the original declared system identifier.
+ </p>
</s2>
</s1>
@@ -372,71 +383,87 @@
]]></source>
</s1>
- <anchor id="imp"/>
- <s1 title="Implementation and default configuration">
+ <anchor id="default"/>
+ <s1 title="Default configuration">
<p>
- The SAX <code>Parser</code> interface provides an <code>entityResolver</code>
- hook to allow an application to resolve the external entities. The Sun
- Microsystems Java code for "<code>resolver.jar</code>" provides a
- CatalogManager. This is incorporated into @docname@ as
- <code>org.apache.cocoon.components.resolver</code> and local configuration
- is achieved via the <code>CatalogManager.properties</code> file.
+ A default catalog and some base entities (e.g. ISO*.pen character
+ entity sets) are included in the @docname@ distribution at
+ <code>webapps/cocoon/resources/entities/</code>
+ - the default catalog is automatically loaded when @docname@ starts.
</p>
- <ul>
- <li>A default catalog and some base entities (e.g. ISO*.pen character
- entity sets) are included in the @docname@ distribution at
- <code>webapps/cocoon/resources/entities/</code>
- </li>
- <li>The default catalog is automatically loaded at startup.
- </li>
- <li>An annotated <code>CatalogManager.properties</code> file is included
- with the distribution to facilitate the configuration of local catalogs.
- </li>
- <li>The automatic default configuration should work out-of-the-box.</li>
- </ul>
-
<p>
- When the parser needs to load a declared entity, then it first consults
- the Catalog Manager to get a possible mapping to an alternate system
- identifier. If there is no mapping for an identifier in the catalogs
- (or in any sub-ordinate catalogs), then @docname@ will carry on to
- retrieve the resource using the original declared system identifier.
- </p>
-
- <p>
If you suspect problems, then you can raise the level of the
<code>verbosity</code> property (to 2 or 3) and watch the messages going
- to stdout when @docname@ starts and operates. You would also do this to
- detect any misconfiguration of your own catalogs.
+ to standard output when @docname@ starts and operates. You would also do
+ this to detect any misconfiguration of your own catalogs.
</p>
</s1>
<anchor id="config"/>
<s1 title="Local configuration">
- <p>
- You can add your own local catalogs using the <code>catalogs</code> property
- in the default properties file. See the notes inside the properties file).
- </p>
+ <p>You can extend the default configuration to include local catalogs
+ for site-specific requirements. This is achieved via various means.
+ </p>
- <p>
- The build process will automatically copy the properties file from
+ <s2 title="Using cocoon.xconf">
+ <p>Parameters (properties) for the resolver component can be specified
+ in the <code>cocoon.xconf</code> configuration file.
+ See the detailed internal notes - here is a precis.
+ </p>
+
+ <ul>
+ <li><code>local-catalog</code>
+ ... The full filesystem pathname to a single local catalog file.
+ </li>
+ <li><code>verbosity</code>
+ ... The level of messages from the resolver
+ (loading catalogs, identifier resolution, etc.)
+ </li>
+ </ul>
+ </s2>
+
+ <s2 title="Using CatalogManager.properties">
+ <p>An annotated <code>CatalogManager.properties</code> file is included
+ with the distribution - modify it to suit your needs. You can add your
+ own local catalogs using the <code>catalogs</code> property.
+ (See the notes inside the properties file).
+ </p>
+
+ <p>
+ The build process will automatically copy the properties file from
<code>$COCOON_HOME/webapp/resources/entities/CatalogManager.properties</code>
- to
+ to
<code>$TOMCAT_HOME/webapps/cocoon/WEB-INF/classes/CatalogManager.properties</code>
- thereby making it available to the Java classpath.
- If you see an error message going to STDOUT when @docname@ starts
- (<code>Cannot find CatalogManager.properties</code>) then this means that
- the properties file is not available to the Java classpath.
- </p>
+ thereby making it available to the Java classpath.
+ </p>
- <p>
- The actual "catalog" files have a powerful set of directives.
- For example, the <strong>CATALOG</strong> directive facilitates the
- inclusion of a sub-ordinate catalog. The list of resources below will
- lead to <link href="#info">further information</link> about catalog usage.
- </p>
+ <p>
+ If you see an error message going to STDOUT when @docname@ starts
+ (<code>Cannot find CatalogManager.properties</code>) then this means that
+ the properties file is not available to the Java classpath. Note that this
+ does not mean that entity resolution is disabled, rather that no local
+ configuration is being effected. Therefore no local catalogs will be
+ loaded and no entity resolution messages will be received (verbosity
+ level is zero by default).
+ </p>
+
+ <p>
+ That may truly be the intention, and not just a configuration mistake.
+ You can still use <code>cocoon.xconf</code> to effect your local
+ configuration.
+ </p>
+ </s2>
+ <s2 title="Resolver directives inside your catalog file">
+ <p>
+ The actual "catalog" files have a powerful set of directives.
+ For example, the <strong>CATALOG</strong> directive facilitates the
+ inclusion of a sub-ordinate catalog. The list of resources below will
+ lead to <link href="#info">further information</link> about catalog usage.
+ </p>
+ </s2>
+
<s2 title="Example local configuration for Simplified DocBook">
<p>
We use the Simplified DocBook XML DTD for some of our documentation.
@@ -456,8 +483,9 @@
with a single entry for the Simplified DocBook XML DTD
</li>
<li>
- appended the full pathname to the <code>catalogs</code> property in the
- <code>CatalogManager.properties</code> file
+ added the parameter (<code>local-catalog</code>) to the
+ <code>cocoon.xconf</code>
+ (using the full pathname to the <code>sdocbook.cat</code> catalog).
</li>
</ul>
@@ -488,6 +516,27 @@
</s2>
</s1>
+ <anchor id="imp"/>
+ <s1 title="Implementation notes">
+ <p>
+ The SAX <code>Parser</code> interface provides an <code>entityResolver</code>
+ hook to allow an application to resolve the external entities. The Sun
+ Microsystems Java code "<code>com.sun.resolver</code>" provides a
+ <strong>Catalog Resolver</strong>. This is incorporated into @docname@ via
+ <code>org.apache.cocoon.components.resolver</code>
+ </p>
+
+ <p>
+ <link href="#default">Default configuration</link> is achieved via
+ <code>org.apache.cocoon.components.resolver.ResolverImpl.java</code>
+ which initialises the catalog resolver and loads a default system catalog.
+ The <code>ResolverImpl.java</code> enables <link href="#config">local
+ configuration</link> by applying properties from the
+ <code>CatalogManager.properties</code> file and then further configuration
+ from <code>cocoon.xconf</code> parameters.
+ </p>
+ </s1>
+
<anchor id="dev"/>
<s1 title="Development notes">
@@ -498,6 +547,7 @@
<ul>
<li>5) ? What other default entities need to be shipped with the @docname@
distribution? We already have some character entity sets (ISO*.pen).
+ Probably also need the documentation DTDs.
</li>
<li>7)
</li>
1.4 +42 -8
xml-cocoon2/src/org/apache/cocoon/components/resolver/ResolverImpl.java
Index: ResolverImpl.java
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/org/apache/cocoon/components/resolver/ResolverImpl.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ResolverImpl.java 2001/09/07 14:13:06 1.3
+++ ResolverImpl.java 2001/10/05 07:27:46 1.4
@@ -7,6 +7,7 @@
*****************************************************************************/
package org.apache.cocoon.components.resolver;
+import com.sun.resolver.helpers.Debug;
import com.sun.resolver.tools.CatalogResolver;
import org.apache.avalon.framework.activity.Disposable;
import org.apache.avalon.framework.component.ComponentException;
@@ -31,10 +32,12 @@
/**
- * A component that uses catalogs for resolving Entities. This implementation uses
the
- * XML Entity and URI Resolvers from http://www.sun.com/xml/developers/resolver/
- * published by Sun's Norman Walsh. More information on the catalogs can be found at
- * http://www.oasis-open.org/committees/entity/spec.html
+ * A component that uses catalogs for resolving Entities. This implementation
+ * uses the XML Entity and URI Resolvers from
+ * http://www.sun.com/xml/developers/resolver/
+ * published by Sun's Norman Walsh. More information on the catalogs can be
+ * found at
+ * http://xml.apache.org/cocoon2/catalog.html
*
* The catalog is by default loaded from "/resources/entities/catalog".
* This can be configured by the "catalog" parameter in the cocoon.xconf:
@@ -43,7 +46,7 @@
* </resolver>
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Davanum Srinivas</a>
- * @version CVS $Revision: 1.3 $ $Date: 2001/09/07 14:13:06 $
+ * @version CVS $Revision: 1.4 $ $Date: 2001/10/05 07:27:46 $
*/
public class ResolverImpl extends AbstractLoggable
implements Resolver, Contextualizable, Composable, Configurable,
ThreadSafe, Disposable {
@@ -64,20 +67,51 @@
}
/**
- * Set the configuration.
+ * Set the configuration. Load the system catalog and apply any
+ * parameters that may have been specified in cocoon.xconf
* @param conf The configuration information
* @exception ConfigurationException
*/
public void configure(Configuration conf) throws ConfigurationException {
Parameters params = Parameters.fromConfiguration(conf);
+
+ // Over-ride the debug level that is set by CatalogManager.properties
+ int debugLevel = Debug.getDebug();
+ // getLogger().debug("Current Catalog verbosity level is "
+ // + debugLevel);
+ String verbosity = params.getParameter("verbosity", "");
+ if (verbosity != "") {
+ getLogger().debug("Setting Catalog verbosity level to "
+ + verbosity);
+ int verbosityLevel = 0;
+ try {
+ verbosityLevel = Integer.parseInt(verbosity);
+ Debug.setDebug(verbosityLevel);
+ } catch (NumberFormatException ce1) {
+ getLogger().warn("Trouble setting Catalog verbosity", ce1);
+ }
+ }
+
// Load the built-in catalog.
- String catalogFile = params.getParameter("catalog",
"/resources/entities/catalog");
+ String catalogFile = params.getParameter("catalog",
+ "/resources/entities/catalog");
try {
String catalogURL = this.context.getRealPath(catalogFile);
- getLogger().debug("Catalog URL is " + catalogURL);
+ getLogger().debug("System Catalog URL is " + catalogURL);
catalogResolver.getCatalog().parseCatalog(catalogURL);
} catch (Exception e) {
getLogger().warn("Could not get Catalog URL", e);
+ }
+
+ // Load a single additional local catalog
+ String localCatalogFile = params.getParameter("local-catalog", "");
+ if (localCatalogFile != "") {
+ try {
+ getLogger().debug("Additional Catalog is " + localCatalogFile);
+ catalogResolver.getCatalog().parseCatalog(localCatalogFile);
+ } catch (Exception e) {
+ getLogger().warn("Could not get local Catalog file", e);
+ }
}
}
1.35 +38 -0 xml-cocoon2/webapp/cocoon.xconf
Index: cocoon.xconf
===================================================================
RCS file: /home/cvs/xml-cocoon2/webapp/cocoon.xconf,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -r1.34 -r1.35
--- cocoon.xconf 2001/09/19 19:37:56 1.34
+++ cocoon.xconf 2001/10/05 07:27:46 1.35
@@ -69,10 +69,48 @@
<parameter name="threadpriority" value="5"/>
</store-janitor>
+ <!-- Entity resolution catalogs:
+ catalog:
+ The default catalog is distributed at /resources/entities/catalog
+ This is the contextual pathname for Cocoon resources.
+ You can override this path, if necessary, using the "catalog" parameter.
+ <parameter name="catalog" value="/resources/entities/catalog"/>
+ However, it is probably desirable to leave this default catalog config
+ and declare your own local catalogs, which are loaded in addition to
+ the system catalog.
+
+ There are various ways to do local configuration (see "Entity Catalogs"
+ documentation). One way is via the CatalogManager.properties file.
+ As an additional method, you can specify the "local-catalog" parameter here.
+
+ local-catalog:
+ The full filesystem pathname to a single local catalog file.
+ <parameter name="local-catalog" value="/usr/local/sgml/mycatalog"/>
+
+ verbosity:
+ The level of messages for status/debug (messages go to standard output)
+ 0 (none) .. 3 (maximum)
+ The following messages are provided ...
+ 0 = none
+ 1 = ? (... not sure yet)
+ 2 = 1+, Loading catalog, Resolved public, Resolved system
+ 3 = 2+, Catalog does not exist, resolvePublic, resolveSystem
+ <parameter name="verbosity" value="2"/>
+
+ -->
+ <resolver class="org.apache.cocoon.components.resolver.ResolverImpl">
+ <parameter name="catalog" value="/resources/entities/catalog"/>
+ <parameter name="verbosity" value="2"/>
+ </resolver>
+
+ <!-- XSLT processor:
+ -->
<xslt-processor class="org.apache.cocoon.components.xslt.XSLTProcessorImpl"
logger="root.xslt">
<parameter name="use-store" value="true"/>
</xslt-processor>
+ <!-- Xpath processor:
+ -->
<xpath-processor class="org.apache.cocoon.components.xpath.XPathProcessorImpl"
logger="root.xslt"/>
<!-- The url factory adds special url protocols to the system, they
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
