You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by pi...@apache.org on 2004/09/27 19:57:28 UTC
svn commit: rev 47321 - cocoon/trunk/src/blocks/scratchpad/java/org/apache/cocoon/transformation
Author: pier
Date: Mon Sep 27 10:57:28 2004
New Revision: 47321
Modified:
cocoon/trunk/src/blocks/scratchpad/java/org/apache/cocoon/transformation/IncludeTransformer.java
Log:
More JavaDOCs, comments, re-indenting, and filtering out the "include" namespaces declarations
Modified: cocoon/trunk/src/blocks/scratchpad/java/org/apache/cocoon/transformation/IncludeTransformer.java
==============================================================================
--- cocoon/trunk/src/blocks/scratchpad/java/org/apache/cocoon/transformation/IncludeTransformer.java (original)
+++ cocoon/trunk/src/blocks/scratchpad/java/org/apache/cocoon/transformation/IncludeTransformer.java Mon Sep 27 10:57:28 2004
@@ -1,146 +1,252 @@
-/*
- * Copyright 1999-2004 The Apache Software Foundation.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package org.apache.cocoon.transformation;
-
-import java.io.IOException;
-import java.io.Serializable;
-import java.util.Map;
-
-import org.apache.avalon.framework.parameters.Parameters;
-import org.apache.avalon.framework.service.ServiceException;
-import org.apache.avalon.framework.service.ServiceManager;
-import org.apache.avalon.framework.service.Serviceable;
-import org.apache.cocoon.ProcessingException;
-import org.apache.cocoon.caching.CacheableProcessingComponent;
-import org.apache.cocoon.components.source.SourceUtil;
-import org.apache.cocoon.components.source.impl.MultiSourceValidity;
-import org.apache.cocoon.environment.SourceResolver;
-import org.apache.cocoon.xml.IncludeXMLConsumer;
-import org.apache.excalibur.source.Source;
-import org.apache.excalibur.source.SourceValidity;
-import org.xml.sax.Attributes;
-import org.xml.sax.SAXException;
-
-/**
- * Simple Source include transformer.
- *
- * <p>
- * Triggers for the element <code>include</code> in the
- * namespace <code>http://apache.org/cocoon/include/1.0</code>.
- * Use <code><include src="scheme://path"/></code>
- * </p>
- *
- * @cocoon.sitemap.component.name include
- * @cocoon.sitemap.component.logger sitemap.transformer.include
- *
- * @cocoon.sitemap.component.pooling.min 2
- * @cocoon.sitemap.component.pooling.max 16
- * @cocoon.sitemap.component.pooling.grow 2
- */
-public class IncludeTransformer extends AbstractTransformer
- implements Serviceable, Transformer,
- CacheableProcessingComponent {
-
- private static final String NS_URI = "http://apache.org/cocoon/include/1.0";
- private static final String INCLUDE_ELEMENT = "include";
- private static final String SRC_ATTRIBUTE = "src";
-
- private ServiceManager m_manager;
- private SourceResolver m_resolver;
- private MultiSourceValidity m_validity;
-
- public IncludeTransformer() {
- }
-
- public void service(ServiceManager manager) throws ServiceException {
- m_manager = manager;
- }
-
- public void setup(SourceResolver resolver, Map om, String src, Parameters parameters)
- throws ProcessingException, SAXException, IOException {
- m_resolver = resolver;
- m_validity = null;
- }
-
- public void recycle() {
- super.recycle();
- m_resolver = null;
- m_validity = null;
- }
-
- public void startDocument()
- throws SAXException {
- // Make sure that we have a validity while processing
- this.getValidity();
- super.startDocument();
- }
-
- public void endDocument()
- throws SAXException {
- // Make sure that the validity is "closed" at the end
- this.m_validity.close();
- super.endDocument();
- }
-
- public void startElement(String uri, String localName, String qName, Attributes atts)
- throws SAXException {
- if (NS_URI.equals(uri)) {
- if (INCLUDE_ELEMENT.equals(localName)) {
- String src = atts.getValue(SRC_ATTRIBUTE);
- Source source = null;
- try {
- source = m_resolver.resolveURI(src);
- m_validity.addSource(source);
- SourceUtil.toSAX(m_manager,
- source,
- "text/xml",
- new IncludeXMLConsumer(super.contentHandler));
- } catch (IOException e) {
- throw new SAXException(e);
- } catch (ProcessingException e) {
- throw new SAXException(e);
- } finally {
- if (source != null) {
- m_resolver.release(source);
- }
- }
- } else {
- getLogger().warn("Unrecognized element <" + qName + ">");
- }
- } else {
- super.startElement(uri, localName, qName, atts);
- }
- }
-
- public void endElement(String uri, String localName, String qName) throws SAXException {
- if (!NS_URI.equals(uri)) {
- super.endElement(uri, localName, qName);
- }
- }
-
- public Serializable getKey() {
- // FIXME: In case of including "cocoon://" or other dynamic sources
- // key has to be dynamic.
- return "I";
- }
-
- public SourceValidity getValidity() {
- if (m_validity == null) {
- m_validity = new MultiSourceValidity(m_resolver, -1);
- }
- return m_validity;
- }
-}
+/*
+ * Copyright 1999-2004 The Apache Software Foundation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.cocoon.transformation;
+
+import java.io.IOException;
+import java.io.Serializable;
+import java.util.Map;
+
+import org.apache.avalon.framework.parameters.Parameters;
+import org.apache.avalon.framework.service.ServiceException;
+import org.apache.avalon.framework.service.ServiceManager;
+import org.apache.avalon.framework.service.Serviceable;
+import org.apache.cocoon.ProcessingException;
+import org.apache.cocoon.caching.CacheableProcessingComponent;
+import org.apache.cocoon.components.source.SourceUtil;
+import org.apache.cocoon.components.source.impl.MultiSourceValidity;
+import org.apache.cocoon.environment.SourceResolver;
+import org.apache.cocoon.xml.IncludeXMLConsumer;
+import org.apache.cocoon.xml.NamespacesTable;
+import org.apache.excalibur.source.Source;
+import org.apache.excalibur.source.SourceValidity;
+import org.xml.sax.Attributes;
+import org.xml.sax.SAXException;
+
+/**
+ * <p>A simple transformer including resolvable sources (accessed through Cocoon's
+ * {@link SourceResolver} from its input.</p>
+ *
+ * <p>Inclusion is triggered by the <code><include ... /></code> element
+ * defined in the <code>http://apache.org/cocoon/include/1.0</code> namespace.</p>
+ *
+ * <p>Example:</p>
+ *
+ * <p><code><incl:include xmlns="http://apache.org/cocoon/include/1.0"
+ * src="cocoon://path/to/include"/></code></p>
+ *
+ * <p>An interesting feature of this {@link Transformer} is that it implements the
+ * {@link CacheableProcessingComponent} interface and provides full support for
+ * caching. In other words, if the input given to this transformer has not changed,
+ * and all of the included sources are (cacheable) and still valid, this transformer
+ * will not force a pipeline re-generation like the {@link CIncludeTransformer}.</p>
+ *
+ * @cocoon.sitemap.component.name include
+ * @cocoon.sitemap.component.logger sitemap.transformer.include
+ *
+ * @cocoon.sitemap.component.pooling.min 2
+ * @cocoon.sitemap.component.pooling.max 16
+ * @cocoon.sitemap.component.pooling.grow 2
+ */
+public class IncludeTransformer extends AbstractTransformer
+implements Serviceable, Transformer, CacheableProcessingComponent {
+
+ private static final String NS_URI = "http://apache.org/cocoon/include/1.0";
+ private static final String INCLUDE_ELEMENT = "include";
+ private static final String SRC_ATTRIBUTE = "src";
+
+ private ServiceManager m_manager;
+ private SourceResolver m_resolver;
+ private MultiSourceValidity m_validity;
+ private NamespacesTable m_namespaces;
+
+ /**
+ * <p>Create a new {@link IncludeTransformer} instance.</p>
+ */
+ public IncludeTransformer() {
+ super();
+ }
+
+ /**
+ * <p>Setup the {@link ServiceManager} available for this instance.</p>
+ *
+ * @see Serviceable#service(ServiceManager)
+ */
+ public void service(ServiceManager manager) throws ServiceException {
+ this.m_manager = manager;
+ }
+
+ /**
+ * <p>Setup this component instance in the context of its pipeline and
+ * current request.</p>
+ *
+ * @see Serviceable#service(ServiceManager)
+ */
+ public void setup(SourceResolver resolver, Map om, String src, Parameters parameters)
+ throws ProcessingException, SAXException, IOException {
+ this.m_resolver = resolver;
+ this.m_validity = null;
+ this.m_namespaces = new NamespacesTable();
+ }
+
+ /**
+ * <p>Recycle this component instance.</p>
+ *
+ * @see org.apache.avalon.excalibur.pool.Recyclable#recycle()
+ */
+ public void recycle() {
+ super.recycle();
+ this.m_resolver = null;
+ this.m_validity = null;
+ this.m_namespaces = new NamespacesTable();
+ }
+
+ /**
+ * <p>Receive notification of the beginning of an XML document.</p>
+ *
+ * @see org.xml.sax.ContentHandler#startDocument()
+ */
+ public void startDocument()
+ throws SAXException {
+ /* Make sure that we have a validity while processing */
+ this.getValidity();
+ super.startDocument();
+ }
+
+ /**
+ * <p>Receive notification of the end of an XML document.</p>
+ *
+ * @see org.xml.sax.ContentHandler#startDocument()
+ */
+ public void endDocument()
+ throws SAXException {
+ /* Make sure that the validity is "closed" at the end */
+ this.m_validity.close();
+ super.endDocument();
+ }
+
+ /**
+ * <p>Receive notification of the start of a prefix mapping.</p>
+ *
+ * <p>This transformer will remove all prefix mapping declarations for those
+ * prefixes associated with the <code>http://apache.org/cocoon/include/1.0</code>
+ * namespace.</p>
+ *
+ * @see org.xml.sax.ContentHandler#startPrefixMapping(String)
+ */
+ public void startPrefixMapping(String prefix, String nsuri)
+ throws SAXException {
+ if (NS_URI.equals(nsuri)) {
+ /* Skipping mapping for the current prefix as it's ours */
+ this.m_namespaces.addDeclaration(prefix, nsuri);
+ } else {
+ /* Map the current prefix, as we don't know it */
+ super.startPrefixMapping(prefix, nsuri);
+ }
+ }
+
+ /**
+ * <p>Receive notification of the end of a prefix mapping.</p>
+ *
+ * <p>This transformer will remove all prefix mapping declarations for those
+ * prefixes associated with the <code>http://apache.org/cocoon/include/1.0</code>
+ * namespace.</p>
+ *
+ * @see org.xml.sax.ContentHandler#endPrefixMapping(java.lang.String)
+ */
+ public void endPrefixMapping(String prefix)
+ throws SAXException {
+ if (NS_URI.equals(this.m_namespaces.getUri(prefix))) {
+ /* Skipping unmapping for the current prefix as it's ours */
+ this.m_namespaces.removeDeclaration(prefix);
+ } else {
+ /* Unmap the current prefix, as we don't know it */
+ super.endPrefixMapping(prefix);
+ }
+ }
+
+ /**
+ * <p>Receive notification of the start of an element.</p>
+ *
+ * @see org.xml.sax.ContentHandler#startElement(String, String, String, org.xml.sax.Attributes)
+ */
+ public void startElement(String uri, String localName, String qName, Attributes atts)
+ throws SAXException {
+ if (NS_URI.equals(uri)) {
+ if (INCLUDE_ELEMENT.equals(localName)) {
+ String src = atts.getValue(SRC_ATTRIBUTE);
+ Source source = null;
+ try {
+ source = m_resolver.resolveURI(src);
+ if (m_validity != null) {
+ m_validity.addSource(source);
+ }
+ SourceUtil.toSAX(m_manager, source, "text/xml",
+ new IncludeXMLConsumer(super.contentHandler));
+ }
+ catch (IOException e) {
+ throw new SAXException(e);
+ }
+ catch (ProcessingException e) {
+ throw new SAXException(e);
+ }
+ finally {
+ if (source != null) {
+ m_resolver.release(source);
+ }
+ }
+ }
+ } else {
+ super.startElement(uri, localName, qName, atts);
+ }
+ }
+
+ /**
+ * <p>Receive notification of the end of an element.</p>
+ *
+ * @see org.xml.sax.ContentHandler#endElement(String, String, String)
+ */
+ public void endElement(String uri, String localName, String qName)
+ throws SAXException {
+ if (!NS_URI.equals(uri)) {
+ super.endElement(uri, localName, qName);
+ }
+ }
+
+ /**
+ * <p>Return the validity key associated with this transformation.</p>
+ *
+ * @see CacheableProcessingComponent#getKey()
+ */
+ public Serializable getKey() {
+ // FIXME: In case of including "cocoon://" or other dynamic sources
+ // key has to be dynamic.
+ return "I";
+ }
+
+ /**
+ * <p>Generate (or return) the {@link SourceValidity} instance used to
+ * possibly validate cached generations.</p>
+ *
+ * @return a <b>non null</b> {@link SourceValidity}.
+ * @see org.apache.cocoon.caching.CacheableProcessingComponent#getValidity()
+ */
+ public SourceValidity getValidity() {
+ if (m_validity == null) {
+ m_validity = new MultiSourceValidity(m_resolver, -1);
+ }
+ return m_validity;
+ }
+}