haul 01/11/23 05:51:59 Modified: webapp Tag: cocoon_20_branch sitemap.xmap Log: Added comments. Revision Changes Path No revision No revision 1.11.2.40 +331 -15 xml-cocoon2/webapp/sitemap.xmap Index: sitemap.xmap =================================================================== RCS file: /home/cvs/xml-cocoon2/webapp/sitemap.xmap,v retrieving revision 1.11.2.39 retrieving revision 1.11.2.40 diff -u -r1.11.2.39 -r1.11.2.40 --- sitemap.xmap 2001/11/06 09:55:38 1.11.2.39 +++ sitemap.xmap 2001/11/23 13:51:59 1.11.2.40 @@ -1,11 +1,49 @@ <?xml version="1.0"?> <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0";> +<!-- + This is the 'heart' of Cocoon. The sitemap maps URI space to + resources. It consists basicly of two parts: components and + pipelines. Pipelines are made out of components. There is such a + vast number of components available that it would be impossible to + describe them here, please refer to the accompanying + documentation. For specific components, have a look also at the + javadocs for them. Most pipelines are present to demonstrate some + feature or technique, often they are explained in more detail in + the accompanying documentation. + + There are some other, less important parts that deal with + resources, views and action sets. For now, ignore them. +--> + + <!-- =========================== Components ================================ --> <map:components> +<!-- + All pipelines consist at least of two components: a generator, that + produces the content and a serialiser, that delivers the content to + the client. + + More precisely: a generator generates SAX events and a serializer + consumes these events and produces a character stream. + + Some things to note here: each generator has a unique name, this + name is mapped to a java class, one name is declared as default + generator. In addition each generator may have additional + configurations as child elements. Additional attributes are targeted + at the component manager. The optional "label" attribute is relevant + for the view concept below. + + It is possible to have the same java class declared as different + generators by using different names. No configuration options are + shared between these instances, however. + + All components follow this schema. +--> + <map:generators default="file"> <map:generator name="file" src="org.apache.cocoon.generation.FileGenerator" label="content" pool-max="32" pool-min="16" pool-grow="4"/> @@ -21,6 +59,16 @@ <map:generator name="stream" src="org.apache.cocoon.generation.StreamGenerator"/> </map:generators> + +<!-- + Transformers can be placed inside the pipeline between the generator + and the serializer. You may have as many transformers as you + like. Transformers consume SAX events and emmit SAX events. + + The "xslt" transformer is an example of a component with additional + configuration. +--> + <map:transformers default="xslt"> <map:transformer name="xslt" src="org.apache.cocoon.transformation.TraxTransformer" pool-max="32" pool-min="16" pool-grow="4"> @@ -41,10 +89,24 @@ <map:transformer name="readDOMsession" src="org.apache.cocoon.transformation.ReadDOMSessionTransformer"/> </map:transformers> +<!-- + Readers are an exception to the above rule that a pipline need to + have exactly one generator and exactly one serializer. Readers + circumvent the XML oriented SAX pipeline model, think of a reader + being a generator and a serializer at once thus a pipeline may not + contain any generator, transformer or serializer in addition to a + reader. They are useful for delivering binary content like images. +--> + <map:readers default="resource"> <map:reader name="resource" src="org.apache.cocoon.reading.ResourceReader"/> </map:readers> +<!-- + Serializers consume SAX events and produce a character stream. Every + pipeline needs to be terminated by a serializer. +--> + <map:serializers default="html"> <map:serializer name="links" src="org.apache.cocoon.serialization.LinkSerializer"/> <map:serializer name="xml" mime-type="text/xml" src="org.apache.cocoon.serialization.XMLSerializer" @@ -70,6 +132,46 @@ </map:serializer> </map:serializers> + +<!-- + Matchers are executed during pipeline setup. They decide if a + pipeline fragment is used within a pipeline. Usually, the decision + is based on a match on the requested URI but matchers exist, that + match different things as well. Most often the fragment contained in + a matcher has a generator as well as a serializer. This is not a + necessity, matchers can be nested while chaining does not work. + Related concepts are selectors and actions. + + Since this is important, let me repeat it: Selectors are executed + during pipeline setup. +--> + + <map:matchers default="wildcard"> + <map:matcher name="wildcard" src="org.apache.cocoon.matching.WildcardURIMatcher"/> + <map:matcher name="regexp" src="org.apache.cocoon.matching.RegexpURIMatcher"/> + <map:matcher name="request" src="org.apache.cocoon.matching.RequestParamMatcher"/> + <map:matcher name="sessionstate" src="org.apache.cocoon.matching.WildcardSessionAttributeMatcher"> + <attribute-name>org.apache.cocoon.SessionState</attribute-name> + </map:matcher> + <map:matcher name="next-page" src="org.apache.cocoon.matching.WildcardParameterValueMatcher"> + <parameter-name>next-state</parameter-name> + </map:matcher> + <map:matcher name="referer-match" src="org.apache.cocoon.matching.WildcardHeaderMatcher"> + <header-name>referer</header-name> + </map:matcher> + </map:matchers> + + +<!-- + Selectors are executed during pipeline setup. They can be used to + determine which pipeline fragments should be combined. They are best + compared with a switch statement in java. Matchers and actions are + related concepts. + + Since this is important, let me repeat it: Selectors are executed + during pipeline setup. +--> + <map:selectors default="browser"> <map:selector name="browser" src="org.apache.cocoon.selection.BrowserSelector"> <!-- # NOTE: The appearance indicates the search order. This is very important since @@ -94,20 +196,14 @@ <map:selector name="parameter" src="org.apache.cocoon.selection.ParameterSelector"/> </map:selectors> - <map:matchers default="wildcard"> - <map:matcher name="wildcard" src="org.apache.cocoon.matching.WildcardURIMatcher"/> - <map:matcher name="regexp" src="org.apache.cocoon.matching.RegexpURIMatcher"/> - <map:matcher name="request" src="org.apache.cocoon.matching.RequestParamMatcher"/> - <map:matcher name="sessionstate" src="org.apache.cocoon.matching.WildcardSessionAttributeMatcher"> - <attribute-name>org.apache.cocoon.SessionState</attribute-name> - </map:matcher> - <map:matcher name="next-page" src="org.apache.cocoon.matching.WildcardParameterValueMatcher"> - <parameter-name>next-state</parameter-name> - </map:matcher> - <map:matcher name="referer-match" src="org.apache.cocoon.matching.WildcardHeaderMatcher"> - <header-name>referer</header-name> - </map:matcher> - </map:matchers> +<!-- + Actions are executed during pipeline setup. Their purpose is to + execute some arbitrary complex code. They are the work horses of + pipelines. Use them to update databases, check external resources + etc. The execution may fail or complete successfully. Only if the + execution was successful, the pipeline fragment contained inside is + used within the pipeline. +--> <map:actions> <map:action name="add-employee" src="org.apache.cocoon.acting.DatabaseAddAction"/> @@ -126,6 +222,11 @@ <!-- =========================== Views =================================== --> +<!-- + Views provide diffent, well, views to resources. Views are + orthogonal to pipelines. Please refer to the docs. +--> + <map:views> <map:view name="content" from-label="content"> <map:serialize type="xml"/> @@ -139,6 +240,13 @@ <!-- =========================== Resources ================================= --> +<!-- + Resources are pipeline fragments that may be used from different + pipeline fragments. For our needs, they behave exactly like + pipelines, only that they are not accessible from outside. + Hence I will explain what's inside below for pipelines. +--> + <map:resources> <map:resource name="slides"> <map:generate src="docs/samples/slides/slides.xml"/> @@ -183,6 +291,12 @@ <!-- ========================== Action sets ================================ --> +<!-- + Action sets group actions together. If some actions are often used + together in pipeline fragments, it's easier to group them and refer + to the group. For more info, please see the docs. +--> + <map:action-sets> <map:action-set name="employee"> <map:act type="add-employee" action="Add"/> @@ -193,6 +307,33 @@ <!-- =========================== Pipelines ================================= --> +<!-- + Pipelines. The beef. Pipelines specify, how the processing of your + content is done. Usually, a pipeline consists of several fragments + that specify the generation, transformation, and serialization of + SAX events. + + Processing is done in two steps: + + 1) The top level elements are executed in order of appearance until + one signals success. These top level elements are usually + matchers. AFAIK other components are not supported for this. + + Other components are called depth-first to determine what + fragments make up the processing pipeline. When a component + fails, no nested components are called but the next component on + the same level. + + 2) Once it is determined which generator, which transformers and + wich serializer is used, these components are executed. During + this, the pipeline may not be changed. + + + You may have as many pipelines in your sitemap as you like. However, + it seems that the only purposes would be to specify different error + handlers or mount subsitemaps. +--> + <map:pipelines> <!-- Utility for viewing source xml or html--> @@ -207,10 +348,47 @@ <!-- sub-sitemap example pipeline --> <map:pipeline> <map:match pattern="sub/**"> + <!-- + matches all URIs starting with "sub/". Have a look at the docs + for this matcher component. + + "*" means, anything that does not contain a path separator, + i.e. slash "/", "**" means anything including path + separators. What is matched by the wildcard is put into + sitemap variables. + + Sitemap variables are organized like a stack, a new set is + placed on top of the already present ones. Any existing + variable can be accessed through a simplified path + expression. These simplified path expression may only use any + number of "../" to refer to the previous levels. + + If a component completes successfully, it sets some sitemap + variables. Their scope is only within the element of that + component. Thus they can only be accessed by nested + components. + --> <map:mount uri-prefix="sub" src="sub/" check-reload="yes"/> + <!-- + Sitemaps may be organized hierarchically. Here such a + subsitemap is "mounted" (think: unix filesystems) to be + responsible for all URIs starting with "sub/". The file + itself is by coincidence located in a subdirectory named + "sub/" as well. There's no need to do that but it is + good practice. The check-reload attributes specifies, if + changed to the subsitemap should result in cocoon rereading the + subsitemap or if they are to be ignored. See docs for + suggestions on this. + + Note here, that all component declarations are inherited to a + subsitemap. + --> </map:match> <map:handle-errors> + <!-- + This pipeline specifies a different error handler. + --> <map:transform src="stylesheets/system/error2html.xsl"/> <map:serialize status-code="500"/> </map:handle-errors> @@ -234,6 +412,15 @@ <map:pipeline> <map:match pattern="documents/index"> <map:redirect-to uri="index.html"/> + <!-- + You may direct a client to a more appropriate URI by the above + command. The above results in a redirect response to the + client. By redirecting to a ressource it would be handled by + cocoon internally. + + Since pipelines work on a first match basis, the above wins the + request although the match below would match as well. + --> </map:match> <map:match pattern="documents/**"> <map:mount uri-prefix="documents" src="documentation/" check-reload="yes"/> @@ -249,10 +436,16 @@ <map:pipeline> <map:match pattern="mount/*/**"> <map:mount uri-prefix="mount/{1}" src="mount/{1}/" check-reload="yes"/> + <!-- + This is an example of using a sitemap variable: "{1}" Curly + brackets denote sitemap variables, here the one named "1". + --> </map:match> </map:pipeline> - <map:pipeline> + + + <map:pipeline> <map:match pattern=""> <map:redirect-to uri="welcome"/> </map:match> @@ -260,6 +453,12 @@ <map:match pattern="welcome"> <map:generate src="docs/samples/samples.xml"/> <!-- + The first 'real' pipeline. The default generator reads from + "docs/samples/samples.xml" and emits SAX events down the + pipeline. Here, the default generator just reads XML from a file, + parses it and generates SAX events while it does so. + --> + <!-- <map:select> <map:when test="wap"> <map:transform src="stylesheets/simple-samples2html.xsl"/> @@ -273,19 +472,62 @@ </map:select> --> <map:transform src="stylesheets/simple-samples2html.xsl"/> + <!-- + These events are consumed by the default transformer, which + uses "stylesheets/simple-samples2html.xsl" as parameter. Since + here the default transformer is an XSLT transformer, the above + stylesheet is applied. As soon as some of the transformation's + result is determined, new SAX events are emitted down the + pipeline. + --> <map:serialize/> + <!-- + Finally, those SAX events are consumed by the default + serializer, assembling a character stream from them which is + send to the client. + + Once a serializer is encountered when assembling the pipeline, + the setup stops and the pipeline is fired up. + --> </map:match> <map:match pattern="welcome-svg"> <map:generate src="docs/samples/samples.xml"/> <map:transform src="stylesheets/svg-samples2html.xsl"/> <map:transform type="extractor"/> + <!-- + Here, several transformers are needed to obtain the desired + result. Note, that the above is not the default transformer but + one named "extractor". Interestingly enough, this transformer + does not need any additional configuration or input. + + If we look at it's javadocs it says: + + "[...] The transformation half of the FragmentExtractor. This + transformer sieves an incoming stream of xml with embedded SVG + images and replaces the images with an xlink locator pointing + to the image. [...]" + + So, this interacts with the fragment below, doing the actual + generating. + --> <map:transform src="stylesheets/fragment-extractor.xsl"/> <map:serialize/> </map:match> <map:match pattern="welcome-svg-images/*.png"> <map:generate type="extractor" src="{1}"/> + <!-- + Again, citing the javadocs: + + "[...] The generation half of + FragmentExtractor. FragmentExtractor is a transformer-generator + pair which is designed to allow sitemap managers to extract + certain nodes from a SAX stream and move them into a separate + pipeline. The main use for this is to extract inline SVG images + and serve them up through a separate pipeline, usually + serializing them to PNG or JPEG format first. [...]" + --> <map:serialize type="svg2png"/> </map:match> @@ -385,6 +627,37 @@ <map:match pattern="news/aggregate.xml"> <map:aggregate element="page" ns="http://foo.bar.com/myspace";> + <!-- + Aggregation is a very powerful concept that allows a document + be generated from several other documents. Strictly speaking, + all parts are just concatenated in this order to a new + document. + + Several things to note here: + + "cocoon:" is a pseudo protocol and refers to another + pipeline. "cocoon:/" refers to a pipeline from the current + sitemap while "cocoon://" refers to a pipeline from the root + sitemap. + + Other pseudo protocols exist: + + "context:" is another pseudo protocol, "context://" is + refering to a resource using the servlet context. + + "resource:" is yet another pseudo protocol, "resource://" is + refering to a resource from the context classloader. + + These pseudo protocols are declared in cocoon.xconf + + Thus the parts refer to the pipeline fragments above. + + The element attribute places the content in a new root element + named as specified, using the namespace provided by the ns + attribute. + + Please see docs for further explanations. + --> <map:part src="cocoon:/slashdot/slashdot.xml" element="slashdot" ns="http://foo.bar.com/slashdot"/> <map:part src="cocoon:/moreover/moreover.xml" element="moreover" ns="http://foo.bar.com/moreover"/> <map:part src="cocoon:/isyndicate/news.xml" element="isyndicate" ns="http://foo.bar.com/isyndicate"/> @@ -439,6 +712,12 @@ <map:match pattern="slides/slides"> <map:redirect-to resource="slides"/> + <!-- + We have seen this before. One difference though, here the + target is specified as a resource. Thus the redirection is done + internally. Conceptually it is more like the pipeline fragment + from the resource is inserted here. Think: macro. + --> </map:match> <map:match pattern="slides/"> @@ -470,6 +749,14 @@ <map:generate type="serverpages" src="docs/samples/xsp/{1}.xsp"/> <map:transform src="stylesheets/dynamic-page2html.xsl"> <map:parameter name="view-source" value="docs/samples/xsp/{1}.xsp"/> + <!-- + Run-time configuration is done through these + <map:parameter/> elements. Again, let's have a look at the + javadocs: + + "[...] All <map:parameter> declarations will be made + available in the XSLT stylesheet as xsl:variables. [...]" + --> </map:transform> <map:serialize/> </map:match> @@ -483,6 +770,12 @@ <map:generate src="docs/samples/sql/{1}.xml"/> <map:transform type="sql"> <map:parameter name="use-connection" value="personnel"/> + <!-- + Let's have a look at the user docs: + + "[...] The purpose of the SQLTransformer is to query a + database and translate the result to XML. [...]" + --> </map:transform> <map:transform src="stylesheets/simple-sql2html.xsl"/> <map:serialize/> @@ -492,6 +785,15 @@ <map:match pattern="forms/employee"> <map:act set="employee"> <map:parameter name="descriptor" value="context://docs/samples/forms/employee.xml"/> + <!-- + Here an action is used. To be precise: all actions that were + grouped together to a set named "employee". See user docs on + actions for more on this. + + This fragment until the closing tag of map:act is only + included if at least one action of this set completes + successfully. + --> <map:generate type="serverpages" src="docs/samples/forms/employee.xsp"/> <map:transform src="stylesheets/dynamic-page2html.xsl"> <map:parameter name="view-source" value="docs/samples/forms/employee.xsp"/> @@ -537,11 +839,23 @@ <!-- ========================== session state ================================= --> <map:match pattern="session-state/example"> + <!-- + This example like the next one show, that matches can be + nested and don't need to match on URIs alone. By using a + session attribute or the referer header for matches it is + easy to model a state machine with the sitemap. + + There are user documents on this. + --> <map:act type="session-isvalid"> + <!-- if session is valid ... --> <map:match type="sessionstate" pattern="1"> + <!-- if a specific session attribute matches pattern "1" --> <map:match type="next-page" pattern="1"> <map:redirect-to resource="dynamic-page1" target="docs/samples/session-state"/> + <!-- by redirecting to this resource, the rest + of this fragment here is irrelevant --> </map:match> <map:match type="next-page" pattern="2"> <map:redirect-to resource="dynamic-page1" target="docs/samples/session-state"/> @@ -559,6 +873,8 @@ <map:redirect-to resource="dynamic-page2" target="docs/samples/session-state/state0"/> </map:act> + <!-- end if session is valid --> + <map:redirect-to resource="dynamic-page" target="docs/samples/session-state/start"/> </map:match>
---------------------------------------------------------------------- In case of troubles, e-mail: [EMAIL PROTECTED] To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
