cziegeler 2002/09/25 23:52:23
Modified: src/documentation/xdocs/userdocs/transformers
cinclude-transformer.xml
src/documentation/xdocs/developing/webapps session.xml
src/java/org/apache/cocoon/webapps/session/context
RequestSessionContext.java
Log:
updating cinclude docs
Revision Changes Path
1.2 +75 -0
xml-cocoon2/src/documentation/xdocs/userdocs/transformers/cinclude-transformer.xml
Index: cinclude-transformer.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/transformers/cinclude-transformer.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- cinclude-transformer.xml 3 Jan 2002 12:31:06 -0000 1.1
+++ cinclude-transformer.xml 26 Sep 2002 06:52:23 -0000 1.2
@@ -14,6 +14,11 @@
</header>
<body>
<s1 title="CInclude Transformer">
+ <p>This transformer includes XML in the current stream and acts therefore
+ is a kind of (dynamic) content aggregation. Two forms, one verbose
+ and flexible approach, and a simple approach are supported by the
+ transformer. We will first discuss the simple approach and
+ the more flexible is mentioned in the next chapter.</p>
<p>
This transformer triggers for the element <code>include</code> in the
namespace "http://apache.org/cocoon/include/1.0";.
@@ -125,5 +130,75 @@
</page>
]]></source>
</s1>
+<s1 title="Including External XML (simple)">
+ <p>One feature of the cinclude transformer (this is currently not
+ supported by the caching cinclude transformer) is including XML
from
+ external sources, e.g. files or from an HTTP server.
+ The <code>cinclude:includexml</code> tag starts including of
XML:</p>
+ <source>
+<cinclude:includexml> <!-- Include XML from HTTP server -->
+ <cinclude:src>http://external.news.com/flashnews.xml</cinclude:src>
+</cinclude:includexml>
+</source>
+ <p> This would be a simple way of "get"ting XML data from an
+ external site. Using this method it is also possible to pass
parameters in the
+ url - just as you would in a "get" sent from a browser.</p>
+ <source>
+<cinclude:includexml> <!-- Include XML from HTTP server -->
+
<cinclude:src>http://external.news.com/flashnews.xml?id=1234&myname=matthew</cinclude:src>
+</cinclude:includexml>
+</source>
+ <p>If the external XML is not valid or not available, the
+ transformer signals an error to the pipeline and the document
containing the
+ include command is not available.</p>
+ <p>For this purpose the <code>ignoreErrors</code> attribute can be
+ used:</p>
+ <source>
+<cinclude:includexml ignoreErrors="true">
+...
+</cinclude:includexml></source>
+ </s1>
+ <s1 title="Including External XML (advanced)">
+ <p>The above section shows you how to include XML data from an
+ external source such as an HTTP server using the simple "get"
method supplied
+ in the HTTP protocol. For more advanced uses you will wish to
be able to send
+ "Post" or other HTTP methods to the server. In addition you
may want to
+ actually send XML data to the server - just as you would
using an HTML form.
+ The format of this resource is slightly more complicated:</p>
+ <source>
+<?xml version="1.0"?>
+<data xmlns:cinclude="http://apache.org/cocoon/include/1.0">
+<cinclude:includexml>
+ <cinclude:src>http://itsunshine/tamino/blah</cinclude:src>
+ <cinclude:configuration>
+ <cinclude:parameter>
+ <cinclude:name>method</cinclude:name>
+ <cinclude:value>POST</cinclude:value>
+ </cinclude:parameter>
+ </cinclude:configuration>
+ <cinclude:parameters>
+ <cinclude:parameter>
+ <cinclude:name>message</session:name>
+ <cinclude:value>Hi there</session:value>
+ </cinclude:parameter>
+ <cinclude:parameter>
+ <cinclude:name>_Process</cinclude:name>
+
<cinclude:value><name>matti</name><age>36</age></cinclude:value>
+ </cinclude:param>
+ </cinclude:parameters>
+</cinclude:includexml>
+</data>
+ </source>
+ <p>Lets look at the tags. The tag <code>cinclude:src</code> defines
the address of the
+ resource we want to access and then comes a list of (optional)
+ connection-specific parameters (enclosed in the
<code>cinclude:configuration</code> tag).
+ In this example the HTTP-method ("POST") is passed into the
connection. The
+ format of these parameters is discussed next.</p>
+ <p>Then comes the list of parameters we wish to pass into the
+ function. Each parameter defined has a name and a value. The
value can either
+ be text or XML.</p>
+ <p>The format of the parameters is the same as for the connection
+ configuration.</p>
+ </s1>
</body>
</document>
1.3 +27 -27
xml-cocoon2/src/documentation/xdocs/developing/webapps/session.xml
Index: session.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/developing/webapps/session.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- session.xml 17 Jul 2002 07:27:08 -0000 1.2
+++ session.xml 26 Sep 2002 06:52:23 -0000 1.3
@@ -198,23 +198,22 @@
</s1>
<s1 title="Special Contexts">
<p>Cocoon creates and maintains special contexts that allow the
- applications to access the environment data. This allows the read-only
access
- to such things as the HttpRequest or the HtppResponse using the same XPath
+ applications to access the environment. This allows the read-only access
+ to such things as the current request or the response using the same XPath
commands previously described. These context do not require any session,
they
- are everytime available.</p>
+ are always available and change on every request.</p>
<s2 title="The Request Context - Accessing the Environment, Part One">
<p>The request context is an XML description of the current
- HttpRequest. This context is a special read only context which can be
accessed
- with the usual commands:</p>
+ (HTTP) request. This context is a special read only context that
+ can be accessed with the usual commands:</p>
<p><em><getxml context="request" path="/parameter"/></em></p>
- <p>If you for example want to get the value of a parameter with the
+ <p>For example, if you want to get the value of a parameter with the
name <em>username</em> you can include the following command in your XML
and it
will be replaced with the value of the parameter:</p>
<p><em><getxml context="request"
path="/parameter/username"/></em></p>
- <p>This command will be replaced with all parameters from the current
- request in XML format. If you wish to obtain the complete querystring as
it was
+ <p>If you wish to obtain the complete querystring as it was
passed into Cocoon - without converting the data to XML - then you can use
the "/querystring" path:</p>
<p><em><getxml context="request"
@@ -224,7 +223,8 @@
<p>The complete context you can access via these commands has the
following XML format:</p>
<source><parameter>
- <!-- All parameters: parameter names build the elements with the values as
text node childs -->
+ <!-- All parameters: parameter names build the elements with the value of the
first parameter with
+ this name as text node child -->
<firstparameter>value of parameter</firstparameter>
<secondparameter>value of parameter</secondparameter>
</parameter>
@@ -233,20 +233,20 @@
(The querystring contains only parameters send by the GET method)
<parametervalues>
- <!-- All parameters. The tags are all inside the session namespace.
- The generated xml can be used without modification for the
- session:connection command. -->
- <session:params>
- <session:param>
- <session:name>1st parameter name</session:name>
- <session:value>1st parameter value</session:value>
- </session:param>
+ <!-- All parameters. The tags are all inside the cinclude transformer
namespace.
+ The generated XML can be used without modification for the
+ cinclude:includexml command. -->
+ <cinclude:parameters>
+ <cinclude:parameter>
+ <cinclude:name>1st parameter name</cinclude:name>
+ <cinclude:value>1st parameter value</cinclude:value>
+ </cinclude:parameter>
...
- <session:param>
- <session:name>2nd parameter name</session:name>
- <session:value>2nd parameter value</session:value>
- </session:param>
- </session:params>
+ <cinclude:parameter>
+ <cinclude:name>2nd parameter name</cinclude:name>
+ <cinclude:value>2nd parameter value</cinclude:value>
+ </cinclude:parameter>
+ </cinclude:parameters>
<!-- If a parameter has more than one value, for each value a
<session:param> block is generated. -->
</parametervalues>
@@ -298,13 +298,13 @@
</s2>
<s2 title="The Response Context - Accessing the Environment, Part Two">
<p>The response context is an XML description of the current
- HttpResponse. This context is a special write only context which can be
+ (HTTP) response. This context is a special write only context that can be
accessed with the usual commands:</p>
<p><em><session:setxml context="response"
path="/header"/></em></p>
<p>This command will be removed from the XML and the information will
- be added to the response. Using the response context headers and cookies
can be
- added.</p>
+ be added to the response. Headers and cookies can be
+ added using the response context .</p>
<s3 title="Adding headers">
<p>Headers can be added either by <em>setxml</em> or by
<em>appendxml</em>. If <em>setxml</em> is used, the header with the
name gets
@@ -337,8 +337,8 @@
<p>The temporary context with the name <em>"temp"</em> is available on
each request. It is independent from the session and has no content when
a new
request starts. It can be used like any other context except that the
content
- is lost when the current response is finished.</p>
- <p>Using the tempory context it is possible to use store any xml
+ is lost/deleted when the current response is finished.</p>
+ <p>Using the tempory context it is possible to store any XML
information for processing the current request.</p>
</s2>
</s1>
1.7 +41 -21
xml-cocoon2/src/java/org/apache/cocoon/webapps/session/context/RequestSessionContext.java
Index: RequestSessionContext.java
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/java/org/apache/cocoon/webapps/session/context/RequestSessionContext.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- RequestSessionContext.java 23 Sep 2002 12:03:27 -0000 1.6
+++ RequestSessionContext.java 26 Sep 2002 06:52:23 -0000 1.7
@@ -62,6 +62,7 @@
import org.apache.cocoon.environment.ObjectModelHelper;
import org.apache.cocoon.environment.Request;
import org.apache.excalibur.source.SourceResolver;
+import org.apache.cocoon.transformation.CIncludeTransformer;
import org.apache.cocoon.webapps.session.SessionConstants;
import org.apache.cocoon.webapps.session.connector.Resource;
import org.apache.cocoon.webapps.session.xml.XMLUtil;
@@ -85,27 +86,31 @@
* It is not allowed to change this context.
* The following paths are valid:
* /parameter - lists all parameters, parameter names build the
- * elements with the values as text node childs
- * /parameter/<parameter_name> - one text node containing the value
+ * elements with the value of the first parameter with
+ * this name as text node childs
+ * /parameter/<parameter_name> - one text node containing the value of the first
+ * parameter with this name
* /querystring - the querystring with a leading '?' or null (the
querystring is only for GET)
*
* /parametervalues - same as /parameter but values are listed as
described
- * below
- * <session:params>
- * <session:param>
- * <session:name>parameter
name</session:name>
- * <session:value>parameter
value</session:value>
- * </session:param>
+ * below and each value of a parameter is listed.
+ * <cinclude:parameters>
+ * <cinclude:parameter>
+ * <cinclude:name>parameter
name</cinclude:name>
+ * <cinclude:value>parameter
value</cinclude:value>
+ * </cinclude:parameter>
* ...
- * <session:param>
- * <session:name>parameter
name</session:name>
- * <session:value>parameter
value</session:value>
- * </session:param>
- * </session:params>
+ * <cinclude:parameter>
+ * <cinclude:name>parameter
name</cinclude:name>
+ * <cinclude:value>parameter
value</cinclude:value>
+ * </session:parameter>
+ * </cinclude:parameters>
* If a parameter has more than one value for each
value a
- * <session:param> block is generated.
+ * <cinclude:parameter/> block is generated.
+ * This output has the namespace of the
CIncludeTransformer
+ * to use it as input for a <cinclude:includexml>
command.
* /attributes - lists all attributes, attribute names build the elements
- * with the values as text node childs
+ * with the values as childs
* /headers - lists all headers, header names build the elements
* with the values as text node childs
* /cookies ----- <cookie name="...">
@@ -150,11 +155,26 @@
public final class RequestSessionContext
implements SessionContext {
+ private static final String PARAMETERS_ELEMENT = "cinclude:" +
CIncludeTransformer.CINCLUDE_PARAMETERS_ELEMENT;
+ private static final String PARAMETER_ELEMENT = "cinclude:" +
CIncludeTransformer.CINCLUDE_PARAMETER_ELEMENT;
+ private static final String NAME_ELEMENT = "cinclude:" +
CIncludeTransformer.CINCLUDE_NAME_ELEMENT;
+ private static final String VALUE_ELEMENT = "cinclude:" +
CIncludeTransformer.CINCLUDE_VALUE_ELEMENT;
+
+ /** Name of this context */
private String name;
+
+ /** The current {@link org.apache.cocoon.environment.Request} */
transient private Request request;
+
+ /** The content of this context */
private Document contextData;
- public void setup(String value, Resource load, Resource save) { name = value; }
+ /**
+ * Setup this context
+ */
+ public void setup(String value, Resource load, Resource save) {
+ this.name = value;
+ }
/**
* Set the Request
@@ -384,7 +404,7 @@
String[] values;
String parValue;
- element = doc.createElementNS(SessionConstants.SESSION_NAMESPACE_URI,
"session:params");
+ element = doc.createElementNS(CIncludeTransformer.CINCLUDE_NAMESPACE_URI,
PARAMETERS_ELEMENT);
parameterValuesElement.appendChild(element);
parameterValuesElement = element;
@@ -419,13 +439,13 @@
try {
// create "/parametervalues" entry
- element =
doc.createElementNS(SessionConstants.SESSION_NAMESPACE_URI, "session:param");
+ element =
doc.createElementNS(CIncludeTransformer.CINCLUDE_NAMESPACE_URI, PARAMETER_ELEMENT);
parameterValuesElement.appendChild(element);
parameter = element;
- element =
doc.createElementNS(SessionConstants.SESSION_NAMESPACE_URI, "session:name");
+ element =
doc.createElementNS(CIncludeTransformer.CINCLUDE_NAMESPACE_URI, NAME_ELEMENT);
parameter.appendChild(element);
element.appendChild(doc.createTextNode(parameterName));
- element =
doc.createElementNS(SessionConstants.SESSION_NAMESPACE_URI, "session:value");
+ element =
doc.createElementNS(CIncludeTransformer.CINCLUDE_NAMESPACE_URI, VALUE_ELEMENT);
parameter.appendChild(element);
element.appendChild(valueNode.cloneNode(true));
} catch (Exception local) {
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
