You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lenya.apache.org by gr...@apache.org on 2003/10/17 06:59:57 UTC
cvs commit: cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/accesscontrol accesscontrollers.xml accesscontrollerresolvers.xml authenticators.xml authorizers.xml policymanagers.xml accreditablemanagers.xml terms.xml
gregor 2003/10/16 21:59:57
Added: src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/tasks
publisher.xml taskaction.xml exporter.xml
scheduling.xml mailtask.xml development.xml
defining.xml anttask.xml concept.xml
src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/accesscontrol
accesscontrollers.xml accesscontrollerresolvers.xml
authenticators.xml authorizers.xml
policymanagers.xml accreditablemanagers.xml
terms.xml
Log:
continued docs restructuring
Revision Changes Path
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/tasks/publisher.xml
Index: publisher.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>The DefaultFilePublisher Task</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<p>
The DefaultFilePublisher is a task that copies XML source files from
the authoring directory to another location, usually the live directory.
It needs the following parameters:
</p>
<ul>
<li><strong>publication-id</strong>: the publication identifier</li>
<li><strong>authoring-path</strong>: the authoring path</li>
<li><strong>tree-authoring-path</strong>: the location of the <code>tree.xml</code> file</li>
<li><strong>live-path</strong>: the live path</li>
<li><strong>tree-live-path</strong>: the location of the <code>tree.xml</code> file</li>
<li><strong>sources</strong>: a comma-separated list of files to publish</li>
</ul>
<p>
All paths are relative to the publication directory. Usually, the path information is read
from the <code>[publication-directory]/config/publishing/publisher.xconf</code> file:
</p>
<source><![CDATA[
<publication>
<authoring>
<documents href="content/authoring"/>
<tree href="content/authoring/tree.xml"/>
</authoring>
<live>
<documents href="content/live"/>
<tree href="content/live/tree.xml"/>
</live>
...
</publication>
]]></source>
<p>
You can override the paths in the task configuration file <code>tasks.xconf</code>,
e. g. to use several publishers to publish into different directories:
</p>
<source><![CDATA[
<tasks>
<task id="publish-test" class="org.apache.lenya.cms.publishing.DefaultFilePublisher">
<label>Publish</label>
<parameter name="live-path" value="content/live-test"/>
<parameter name="tree-live-path" value="content/live-test/tree.xml"/>
</task>
<task id="publish-real" class="org.apache.lenya.cms.publishing.DefaultFilePublisher">
<label>Publish</label>
<parameter name="live-path" value="content/live"/>
<parameter name="tree-live-path" value="content/live/tree.xml"/>
</task>
</tasks>
]]></source>
<p>
The remaining parameters, <code>publication-id</code> and <code>sources</code>, are
passed to the task as request parameters.
</p>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/tasks/taskaction.xml
Index: taskaction.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>The TaskAction: Triggering a Task from the Sitemap</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Declaring the Action</title>
<p>
To invoke a task from a sitemap pipeline, you use a <code>TaskAction</code>. The
task ID is handled to the action by a <code>task</code> parameter:
</p>
<source><![CDATA[
<map:components>
...
<map:actions>
<map:action name="publisher"
src="org.lenya.cms.cocoon.acting.TaskAction">
<task id="publish"/>
</map:action>
</map:actions>
...
</map:components>
]]></source>
<p>
The <code>TaskAction</code> collects the request parameters and forwards them
to the task.
</p>
<source><![CDATA[
<map:match pattern="lenya/publish*">
<map:act type="publisher">
<map:redirect-to uri="{parent_uri}" session="true"/>
</map:act>
<map:redirect-to uri="publishScreen?status=failed" session="true"/>
</map:match>
]]></source>
<p>
You can also pass the task ID as a <code>task-id</code> parameter directly in the pipeline:
</p>
<source><![CDATA[
<map:actions>
<map:action name="task" src="org.lenya.cms.cocoon.acting.TaskAction"/>
</map:actions>
...
<map:match pattern="lenya/publish*">
<map:act type="task">
<map:parameter name="task-id" value="publish-article"/>
<map:redirect-to uri="{parent_uri}" session="true"/>
</map:act>
<map:redirect-to uri="publishScreen?status=failed" session="true"/>
</map:match>
]]></source>
</section>
<section><title>Scheduling a Task</title>
<p>
See section <strong>Scheduler</strong>.
</p>
</section>
<section><title>Developing Your Own Tasks</title>
<p>
Every task must implement the <code>org.lenya.cms.task.Task</code> interface.
</p>
<p>
The easiest way to develop your own task is to extend the <code>AbstractTask</code> class.
Its <code>parameterize()</code> method simply replaces old parameter values with new
ones. All you have to do is implementing the <code>execute(String contextPath)</code>
method.
</p>
<p>
You may wonder why we pass the <code>contextPath</code> as a method parameter
since we already pass it as a task parameter. This ensures that the task is always
able to access the Lenya CMS directory, even if it is not created by a <code>TaskAction</code>
or a <code>TaskJob</code>. Furthermore, if you enter a task in the <code>jobs.xml</code>
file manually, you won't have to provide a hard-coded <code>servlet-context</code> parameter.
</p>
<p>
<strong>This feature may be subject to changes. If you have any suggestions to improve
the task implementation, just contact me (Andreas Hartmann) at</strong>
<link href="mailto:ah@wyona.org">ah@wyona.org</link>.
</p>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/tasks/exporter.xml
Index: exporter.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>The StaticHTMLExporter Task</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<p>
The StaticHTMLExporter is a task that downloads HTML pages from a server and
saves them as HTML files. It needs the following
parameters:
</p>
<ul>
<li><strong>server-uri</strong>: the server uri, e. g. <code>http://authoring.yourdomain.com</code></li>
<li><strong>server-port</strong>: the server port, e. g. 8080</li>
<li><strong>publication-id</strong>: the publication id</li>
<li><strong>export-path-prefix</strong>: the path to save the files to</li>
<li><strong>uris</strong>: a comma-separated list of uris to download (without server + port)</li>
<li><strong>substitute-regexp</strong>: a regular expression to substitute a part of the path</li>
</ul>
<p>
Usually, the path information is read
from the <code>[publication-directory]/config/publishing/publisher.xconf</code> file:
</p>
<source><![CDATA[
<publication>
...
<export>
<destination href="work/export/pending"/>
<substitution regexp="s/\/lenya\/unipublic//g"/>
</export>
</publication>
]]></source>
<p>
You can override the paths in the task configuration file <code>tasks.xconf</code>,
e. g. to use several publishers to publish into different directories:
</p>
<source><![CDATA[
<tasks>
<task id="export-pending" class="org.apache.lenya.cms.publishing.StaticHTMLExporter">
<parameter name="export-path" value="work/export/pending"/>
<parameter name="substitute-regexp" value="s/\/lenya\/your-publication//g"/>
</task>
<task id="export-backup" class="org.apache.lenya.cms.publishing.StaticHTMLExporter">
<parameter name="export-path" value="work/backup"/>
<parameter name="substitute-regexp" value="s/\/lenya\/your-publication//g"/>
</task>
</tasks>
]]></source>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/tasks/scheduling.xml
Index: scheduling.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Scheduling a Task</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<section><title>Scheduling a Task</title>
<p>
See section <strong>Scheduler</strong>.
</p>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/tasks/mailtask.xml
Index: mailtask.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>The MailTask</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<p>
A <code>MailTask</code> sends an e-mail. The parameters, such as recipient
address, subject, and body, can either be provided as a task parameter or
extracted from an XML document.
</p>
<section>
<title>Task Parameters</title>
<p>
The following parameters must be provided:</p>
<ul>
<li><strong>server</strong>: the SMTP server URI</li>
<li><strong>from</strong>: you@yourhost.com</li>
<li><strong>to</strong>: friend@mail.com</li>
<li><strong>cc</strong>: other-friends@mail.com</li>
<li><strong>subject</strong>: Hello World!</li>
<li><strong>body</strong>: How are you?</li>
</ul>
<section><title>Getting the mail data from an XML source</title>
<p>
Additionally, you can pass a <code>uri</code> parameter to the <code>MailTask</code>:</p>
<ul>
<li><strong>uri</strong>: the URI to get the XML file from</li>
</ul>
<p>If this parameter is present, the task tries to fetch an XML document from the URI.
If the parameter <code>uri</code> starts with a <code>http://</code> or <code>ftp://</code>
prefix, the absolute URI is used. If not, the URI is interpreted as relative to the
local publication.</p>
<p>
A complete XML document could look like this:
</p>
<source><![CDATA[
<mail:mail xmlns:mail="http://apache.org/cocoon/lenya/mail/1.0">
<mail:server>mail.yourhost.com</mail:server>
<mail:from>you@yourhost.com</mail:from>
<mail:to>friend@mail.com</mail:to>
<mail:cc>other-friends@mail.com</mail:cc>
<mail:subject>Hello Friends!</mail:subject>
<mail:body>How are you?</mail:body>
</mail:mail>
]]></source>
<p>
All child elements of <code><mail:mail></code> are optional.
If the <code>uri</code> task parameter is provided, the XML
document is fetched from the URI and the parameters are extracted.
</p>
<p>
Task parameters have a higher priority than elements of the document. This makes it
possible to access one complete XML file from different <code>MailTask</code>s and override
the recepient address or other values.
</p>
</section>
</section>
<section><title>Declaring and Using the MailTask</title>
<p>
In <code>tasks.xconf</code>, a typical mail task looks like follows:
</p>
<source><![CDATA[
<task id="send-newsletter" class="org.lenya.cms.mail.MailTask">
<label>Send Newsletter</label>
<parameter name="server" value="mail.example.com"/>
<parameter name="from" value="info@example.com"/>
<parameter name="to" value="newsletter-subscribers@example.com"/>
<parameter name="uri" value="/authoring/newsletter/mail.xml"/>
</task>
]]></source>
<p>
The actual newsletter is received from the URI that is interpreted
relativly to the publication URI. The task can be invoked in a sitemap pipeline:
</p>
<source><![CDATA[
<map:action name="task" src="org.lenya.cms.cocoon.acting.TaskAction"/>
...
<map:match pattern="newsletter/send">
<map:act type="task">
<map:parameter name="task-id" value="send-newsletter"/>
<map:redirect-to uri="report-success.html" session="true"/>
</map:act>
<map:redirect-to uri="report-failure.html" session="true"/>
</map:match>
]]></source>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/tasks/development.xml
Index: development.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Developing Your Own Tasks</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<p>
Every task must implement the <code>org.lenya.cms.task.Task</code> interface.
</p>
<p>
The easiest way to develop your own task is to extend the <code>AbstractTask</code> class.
Its <code>parameterize()</code> method simply replaces old parameter values with new
ones. All you have to do is implementing the <code>execute(String contextPath)</code>
method.
</p>
<p>
You may wonder why we pass the <code>contextPath</code> as a method parameter
since we already pass it as a task parameter. This ensures that the task is always
able to access the Lenya CMS directory, even if it is not created by a <code>TaskAction</code>
or a <code>TaskJob</code>. Furthermore, if you enter a task in the <code>jobs.xml</code>
file manually, you won't have to provide a hard-coded <code>servlet-context</code> parameter.
</p>
<p>
<strong>This feature may be subject to changes. If you have any suggestions to improve
the task implementation, just contact me (Andreas Hartmann) at</strong>
<link href="mailto:andreas@apache.org">andreas@apache.org</link>.
</p>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/tasks/defining.xml
Index: defining.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Defining Tasks</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<p>
All tasks to be used in a publication must be declared in the file
<code>[publication-directory]/content/tasks.xconf</code>.
A typical task configuration file looks like follows:
</p>
<source><![CDATA[
<?xml version="1.0"?>
<tasks>
<!-- publish page -->
<task id="publish">
<label>Publish</label>
<task id="publish" class="org.lenya.cms.publishing.DefaultFilePublisher">
<parameter name="live-path" value="content/live"/>
<parameter name="tree-live-path" value="content/live/tree.xml"/>
</task>
<task id="export" class="org.lenya.cms.publishing.StaticHTMLExporter">
<parameter name="export-path" value="resources/export/pending"/>
<parameter name="substitute-regexp" value="s/\/lenya\/your-publication//g"/>
</task>
</task>
<!-- print message -->
<task id="hello-world" class="org.lenya.cms.task.HelloWorldTask">
<label>Print Message</label>
</task>
</tasks>
]]></source>
<p>
Every task must have a unique <code>id</code> attribute. This identifier is
used to address the task from the sitemap.
Every top-level task must have a child element <code><label></code>. The
content of this element is used, e. g., by the scheduler to let the user choose
a task from a list. The actual implementation of a task is identified using the
<code>class</code> attribute.
</p>
<section><title>Parameters</title>
<p>
Usually, a task needs some parameters to be executed properly.
There are two possibilities to pass parameters to a task:</p>
<ol>
<li>
You can define all parameters or a subset of them in the <code>tasks.xconf</code> file.
</li>
<li>
The remainig parameters can be handled to the <code>TaskAction</code> or the
<code>TaskJob</code> that executes the task. Request parameters always have a higher
priority than parameters from the <code>tasks.xconf</code> file.
</li>
</ol>
<p>
To simplifiy the passing of parameters to tasks, the <code>TaskAction</code> and
<code>TaskJob</code> objects create some default parameters based on
the request and session objects:</p>
<ul>
<li>
<code>Task.PARAMETER_SERVLET_CONTEXT</code> - the path of the servlet context<br/>
<code>/home/user_id/build/jakarta-tomcat/webapps/lenyacms</code>
</li>
<li>
<code>Task.PARAMETER_SERVER_URI</code> - the server URI<br/>
<code>http://www.yourhost.com:8080/lenya/publication/index.html</code>
</li>
<li>
<code>Task.PARAMETER_SERVER_PORT</code> - the server port<br/>
<code>http://www.yourhost.com:8080/lenya/publication/index.html</code>
</li>
<li>
<code>Task.PARAMETER_CONTEXT_PREFIX</code> - the part of the URI that precedes the publication ID<br/>
<code>http://www.yourhost.com:8080/lenya/publication/index.html</code>
</li>
<li>
<code>Task.PARAMETER_PUBLICATION_ID</code> - the publication ID<br/>
<code>http://www.yourhost.com:8080/lenya/publication/index.html</code>
</li>
</ul>
</section>
<section><title>Task Sequences</title>
<p>
Tasks can be nested using so-called <em>task sequences</em>. Sub-tasks of other
tasks don't need to have <code><label></code> elements because they can't
be addressed independently. Whenever a task sequence is executed, all sub-tasks
are executed in the same order as they are declared.
</p>
<p>
When you group tasks, the enclosing <code><task></code> element does not
need a <code><class></code> attribute. If you omit it, the <code>TaskSequence</code>
class is used as default. If you want to implement your own task grouping
mechanism using a subclass of <code>TaskSequence</code>, you can append a
class attribute.
</p>
<p>
All parameters that are passed to a TaskSequence are forwarded to all tasks
in the sequence. By creating a subclass of <code>TaskSequence</code> you could implement
a parameter selection mechanism, e. g. using namespace prefixes.
</p>
</section>
<section><title>Assigning Tasks to Document Types</title>
<p>
Every document type can support a set of tasks. The labels of these tasks
are displayed on the scheduler screen of a document of this type.
To assign a task to a document type, you have to edit the file
<code>[publication-directory]/config/doctypes/doctypes.xconf</code>:
</p>
<source><![CDATA[
<doctypes>
<doc type="Simple-Document">
<tasks>
<task id="publish"/>
<task id="backup"/>
...
</tasks>
</doc>
...
</doctypes>
]]></source>
<p>
You can associate every task with an arbitrary number of document types.
</p>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/tasks/anttask.xml
Index: anttask.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>The AntTask</title>
<version>0.1</version>
<type>Documentation</type>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<p>
The <code>org.apache.lenya.cms.task.AntTask</code> class can be used to invoke targets
of an Ant project.
</p>
<section>
<title>Task Parameters</title>
<p>
The task parameters are:
</p>
<ul>
<li><strong><code>publication-id</code></strong>: The publication ID</li>
<li><strong><code>buildfile (optional)</code></strong>: The location of the build file
relative to the publication directory. If this parameter is
not provided, the file is loaded from the default location (see section <link href="#File+Locations">File Locations</link>).</li>
<li><strong><code>target (optional)</code></strong>: The build target. If this parameter
is not provided, the default target is executed.</li>
<li><strong><code>properties.*</code></strong>: The project properties.</li>
<li><strong><code>ant.*</code></strong>: The command-line parameters for Ant <strong>(not implemented yet!)</strong></li>
</ul>
</section>
<section>
<title>Logging</title>
<p>
Every time an <code>AntTask</code> is invoked, a log file is created unsing
the <code>XmlLogger</code>
(<link href="http://ant.apache.org/manual/listeners.html">manual entry</link>,
<link href="http://nagoya.apache.org/gump/javadoc/ant/build/javadocs/org/apache/tools/ant/XmlLogger.html">JavaDoc</link>).
For the location of the log files, see section <link href="#File+Locations">File Locations</link>.
The log history can be viewed at the URI
</p>
<source>
http://.../<publication>/logs/tasks/index.html
</source>
</section>
<section>
<title>Writing AntTask Buildfiles</title>
<p>
Any Ant project file can be used as a buildfile for the <code>AntTask</code>.
There is one implicit property that is always set when an
<code>AntTask</code> is executed:
</p>
<ul>
<li><strong><code>pub.dir</code></strong>: The absolute path of publication directory.</li>
</ul>
<p>
The runtime properties of the target can be set using task parameters
with the prefix <code>properties</code>, e. g. <code>properties.filename</code>
for a buildfile property named <code>filename</code>.
</p>
</section>
<section>
<title>Using custom Ant Tasks</title>
<p>
The implementation of custom Ant tasks is described in the
<link href="http://ant.apache.org/manual/index.html">Ant User Manual</link>.
If you want to write a general Lenya task, put it into the package
<code>org.lenya.cms.ant</code>. If you want to write a task
that is only suited for your publication, put it in the
<code><publication>/java/src/</code> directory.
</p>
</section>
<section>
<title>File Locations</title>
<p>Default buildfile location:</p>
<source><publication>/config/tasks/targets.xml</source>
<p>Log files:</p>
<source><publication>/logs/tasks/*.xml</source>
<p>Log file presentation stylesheets:</p>
<source><webapp>/lenya/xslt/logs/*.xsl</source>
</section>
<section>
<title>Example</title>
<p>
The following buildfile contains the target <code>publish</code>
that can be invoked using the <code>AntTask</code>:
</p>
<source>
<![CDATA[<project name="Example Project" default="publish" basedir=".">
<!-- implicit properties (set by the AntTask) -->
<property name="pub.dir" value=""/>
<!-- publishing properties -->
<property name="authoring.dir" value="content/authoring"/>
<property name="live.dir" value="content/live"/>
<property name="publish.sources" value=""/>
<target name="publish">
<echo>Publish: Copying files from ${authoring.dir} to ${live.dir}</echo>
<copy todir="${pub.dir}/${live.dir}">
<fileset dir="${pub.dir}/${authoring.dir}">
<include name="${publish.sources}"/>
</fileset>
</copy>
</target>
</project>]]>
</source>
<p>
You define the task in your <code>tasks.xconf</code> file:
</p>
<source>
<![CDATA[<task id="ant" class="org.lenya.cms.task.AntTask"/>]]>
</source>
<p>
To invoke the task from your sitemap, you have to define an appropriate
<code>TaskAction</code> instance:
</p>
<source>
<![CDATA[<map:action name="publish"
src="org.lenya.cms.cocoon.acting.TaskAction">
<task id="ant"/>
</map:action>]]>
</source>
<p>
You call the action in a pipeline:
</p>
<source>
<![CDATA[<map:match pattern="publish.html">
<map:act type="publish">
...
</map:act>
</map:match>]]>
</source>
<p>And finally, go to your browser and call the URI with the appropriate
parameter(s):</p>
<source>http://.../publish.html?properties.publish.sources=test.xml</source>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/tasks/concept.xml
Index: concept.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>The Task Concept</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Andreas Hartmann" email="andreas.hartmann@wyona.org"/>
</authors>
</header>
<body>
<p>
In Lenya CMS, a <strong>task</strong> is used to implement a process
which can be invoked by the user. Tasks are triggered
from the sitemap using a <link href="taskaction.html"><code>TaskAction</code></link>
or <link href="scheduling.html">scheduled</link> using a <code>TaskJob</code>.
</p>
<p>
Typical tasks are
</p>
<ul>
<li>publishing a page,</li>
<li>exporting a page to a live server,</li>
<li>manipulating a file,</li>
<li>sending an e-mail, or</li>
<li>creating a backup of your site.</li>
</ul>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/accesscontrol/accesscontrollers.xml
Index: accesscontrollers.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Access Controllers</title>
<version/>
<type/>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Introduction</title>
<p>An access controller can be used to authenticate entities and to authorize
requests.</p>
</section>
<section>
<title>Defining the Role in lenya.roles</title>
<source><![CDATA[<role name="org.apache.lenya.cms.ac2.AccessController"
shorthand="access-controller"
default-class="org.apache.lenya.cms.ac2.BypassableAccessController"/>]]></source>
</section>
<section>
<title>Declaring an AccessController in cocoon.xconf</title>
<p>
Each AccessController component needs a type that is attached to the
role attribute, separated with a slash (/). This allows you to choose an
AccessController in your publication in combination with the
Publication<link href="accesscontrollerresolvers.html">AccessControllerResolver</link>.
The following example shows the declaration of an AccessController with
the type <em>global</em>:
</p>
<source><![CDATA[<component logger="lenya.ac.accesscontroller.global"
class="org.apache.lenya.cms.ac2.BypassableAccessController"
role="org.apache.lenya.cms.ac2.AccessController/global">
...
</component>]]></source>
</section>
<section>
<title>Default Access Controller</title>
<p>The DefaultAccessController combines an
<link href="authenticators.html">Authenticator</link>, a set of
<link href="authorizers.html">Authorizers</link>, an
<link href="accreditablemanagers.html">AccreditableManager</link> and a
<link href="policymanagers.html">PolicyManager</link> to perform these tasks.</p>
<section>
<title>Declaring an DefaultAccessController in cocoon.xconf</title>
<p>
The DefaultAccessController configuration includes the configuration
of its sub-components, as you see in the following example:
</p>
<source><![CDATA[<component logger="lenya.ac.accesscontroller.global"
class="org.apache.lenya.cms.ac2.DefaultAccessController"
role="org.apache.lenya.cms.ac2.AccessController/global">
<accreditable-manager type="file">
<parameter name="directory"
value="context:///lenya/config/ac/passwd"/>
</accreditable-manager>
<policy-manager type="file"/>
<authorizer type="policy"/>
<authorizer type="workflow"/>
<authorizer type="usecase"/>
</component>]]></source>
</section>
</section>
<section>
<title>Bypassable Access Controller</title>
<p>The BypassableAccessController is a DefaultAccessController that can be
bypassed for certain URL patterns. For URLs that match those patterns
(regular expressions), access is granted for free.</p>
<section>
<title>Declaring an DefaultAccessController in cocoon.xconf</title>
<p>
In addition to the DefaultAccessController, the BypassableAccessController
allows the definition of a regular expresssion for the public URL
patterns:
</p>
<source><![CDATA[<component logger="lenya.ac.accesscontroller.global"
class="org.apache.lenya.cms.ac2.BypassableAccessController"
role="org.apache.lenya.cms.ac2.AccessController/global">
...
<public>.*[.]css|.*[.]jpg|.*[.]gif</public>
</component>]]></source>
</section>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/accesscontrol/accesscontrollerresolvers.xml
Index: accesscontrollerresolvers.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Access Controller Resolvers</title>
<version/>
<type/>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Introduction</title>
<p>An AccessControllerResolver resolves the appropriate AccessController for a URL.</p>
</section>
<section>
<title>Defining the Roles in lenya.roles</title>
<p>To obtain an AccessControllerResolver, the AccessControllerResolverSelector is
used. A component which wants to obtain an AccessController asks the
selector for the <code>composable</code> AccessControllerResolver.
The <code>composable</code> AccessControllerResolver itself uses the
selector to obtain its child AccessControllerResolvers.
</p>
<source><![CDATA[<role name="org.apache.lenya.cms.ac2.AccessControllerResolverSelector"
shorthand="access-controller-resolvers"
default-class="org.apache.avalon.excalibur.component.ExcaliburComponentSelector">
<hint shorthand="configurable"
class="org.apache.lenya.cms.ac2.ConfigurableAccessControllerResolver"/>
<hint shorthand="publication"
class="org.apache.lenya.cms.ac2.PublicationAccessControllerResolver"/>
<hint shorthand="composable"
class="org.apache.lenya.cms.ac2.ComposableAccessControllerResolver"/>
</role>]]></source>
</section>
<section>
<title>Declaring the Access Controller Resolvers in cocoon.xconf</title>
<source><![CDATA[<access-controller-resolvers>
<component-instance logger="lenya.ac.accesscontrollerresolver.publication"
class="org.apache.lenya.cms.ac2.PublicationAccessControllerResolver"
name="publication">
</component-instance>
<component-instance logger="lenya.ac.accesscontrollerresolver.global"
class="org.apache.lenya.cms.ac2.ConfigurableAccessControllerResolver"
name="global">
<access-controller type="global"/>
</component-instance>
<component-instance logger="lenya.ac.accesscontrollerresolver.composable"
class="org.apache.lenya.cms.ac2.ComposableAccessControllerResolver"
name="composable">
<resolver type="publication"/>
<resolver type="global"/>
</component-instance>
</access-controller-resolvers>]]></source>
</section>
<section>
<title>Publication Access Controller Resolver</title>
<p>The PublicationAccessControllerResolver looks for a <code>config/ac.xconf</code>
file inside the publication. If you want to use multiple AccessControllers
within your Lenya installation, just declare them in the <code>
cocoon-xconf.xsl</code> file and choose the type in the <code>
config/ac.xconf</code> file:</p>
<source><![CDATA[<?xml version="1.0"?>
<access-controller type="publication-file">
<authorizer type="usecase">
<config-file
src="context:///lenya/pubs/default/config/ac/usecase-policies.xml"/>
</authorizer>
<accreditable-manager>
<parameter name="directory"
value="context:///lenya/pubs/default/config/ac/passwd"/>
</accreditable-manager>
</access-controller>]]></source>
<p>As you see here, you can put additional configuration code inside the
<code><![CDATA[<access-controller>]]></code> element. This allows you to use
the same AccessController type for multiple publications with different
configurations.</p>
</section>
<section>
<title>Configurable Access Controller Resolver</title>
<p>The ConfigurableAccessControllerResolver can be configured with an
AccessController directly inside <code>cocoon.xconf</code>:</p>
<source><![CDATA[<component-instance logger="lenya.ac.accesscontrollerresolver"
class="org.apache.lenya.cms.ac2.ConfigurableAccessControllerResolver"
name="global">
<access-controller type="global"/>
</component-instance>]]> </source>
</section>
<section>
<title>Composable Access Controller Resolver</title>
<p>The ComposableAccessControllerResolver is configured with a list of
AccessControllerResolvers. Each one of these resolvers is invoked until one
is successful. If no resolver finds an AccessController, the
ComposableAccessControllerResolver returns <code>null</code>.</p>
<source><![CDATA[<component-instance logger="lenya.ac.accesscontrollerresolver"
class="org.apache.lenya.cms.ac2.ComposableAccessControllerResolver"
name="composable">
<resolver type="publication"/>
<resolver type="global"/>
</component-instance>]]></source>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/accesscontrol/authenticators.xml
Index: authenticators.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Authenticators</title>
<version/>
<type/>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Introduction</title>
<p>An authenticator is used to identify a client.</p>
</section>
<section>
<title>Declaring the Roles in lenya.roles</title>
<source><![CDATA[<role name="org.apache.lenya.cms.ac2.Authenticator"
shorthand="authenticator"
default-class="org.apache.lenya.cms.ac2.UserAuthenticator"/>]]></source>
</section>
<section>
<title>UserAuthenticator</title>
<p>The UserAuthenticator uses the request parameters</p>
<ul>
<li><code>username</code> and</li>
<li><code>password</code></li>
</ul>
<p>to authenticate or reject a user.</p>
<source><![CDATA[<component logger="lenya.ac.authenticator"
class="org.apache.lenya.cms.ac2.UserAuthenticator"
role="org.apache.lenya.cms.ac2.Authenticator"/>]]></source>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/accesscontrol/authorizers.xml
Index: authorizers.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Authorizers</title>
<version/>
<type/>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Introduction</title>
<p>An authorizer checks if an identity is authorized to invoke a certain request. The DelegatingAuthorizerAction tries to resolve an AccessController for the URL. If an AccessController could be resolved, its Authorizer is used to authorize the request. If no AccessController could be found, the access to the request is granted for free.</p>
</section>
<section>
<title>PolicyAuthorizer</title>
<p>A PolicyAuthorizer uses policies for authorizing.</p>
</section>
<section>
<title>UsecaseAuthorizer</title>
<p>This authorizer looks for the <code>lenya.usecase</code> request
parameter and checks the usecase policy file for the roles that are
allowed to execute this usecase. The location of this file is defined
using the <code><![CDATA[<config-file>]]></code> tag:</p>
<source><![CDATA[<authorizer type="usecase">
<config-file src="context:///lenya/pubs/default/config/ac/usecase-policies.xml"/>
</authorizer>]]></source>
<p>The usecase policy file might look as follows:</p>
<source><![CDATA[<?xml version="1.0"?>
<usecases xmlns="http://apache.org/cocoon/lenya/ac/1.0">
<usecase id="create">
<role id="editor"/>
</usecase>
</usecases>]]></source>
</section>
<section>
<title>WorkflowAuthorizer</title>
<p>The WorkflowAuthorizer is responsible for protecting workflow
transitions. Therefore it</p>
<ul>
<li>looks for the <code>lenya.event</code> request parameter,</li>
<li>determines the current state of the workflow instance, and</li>
<li>checks if the event may be invoked by one of the current roles in this
state.</li>
</ul>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/accesscontrol/policymanagers.xml
Index: policymanagers.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Policy Managers</title>
<version/>
<type/>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Introduction</title>
<p>A PolicyManager is used to resolve the policy for a certain URL. Lenya ships with the following PolicyManagers:</p>
</section>
<section>
<title>InheritingPolicyManager</title>
<p>This PolicyManager merges the policies of all steps in the URL. For each
URL, a <em>url policy</em> and a <em>subtree policy</em> can be defined.
The InheritingPolicyManager adds the credentials of</p>
<ul>
<li>the subtree policies for all parent directories of the requested page,</li>
<li>the subtree policy of the requested page, and</li>
<li>the url policy of the requested page.</li>
</ul>
<p>For instance, if the URL is <code>/lenya/news/index.html</code>, the
following policies are merged:</p>
<ul>
<li>subtree policy of <code>/</code></li>
<li>subtree policy of <code>/lenya</code></li>
<li>subtree policy of <code>/lenya/news</code></li>
<li>subtree policy of <code>/lenya/news/index</code></li>
<li>url policy of <code>/lenya/news/index</code></li>
</ul>
</section>
<section>
<title>FilePolicyManager</title>
<p>The FilePolicyManager is an InheritingPolicyManager. The policies are defined by policy files that are arranged as a directory tree that reflects the URI space, e.g.:
</p>
<source>/subtree-policy.acml
/lenya/subtree-policy.acml
/lenya/news/index.html/subtree-policy.acml
/lenya/news/index.html/url-policy.acml</source>
<p>If a certain policy file does not exist (like /lenya/news in the above example), an empty policy is used instead.</p>
</section>
<section>
<title>PublicationFilePolicyManager</title>
<p>This PolicyManager does the same as the FilePolicyManager, except that
the current publication is determined and the policy files are resolved
relatively to the <code>publication/config/ac/policies</code> directory.</p>
</section>
<section>
<title>SitemapPolicyManager</title>
<p>The SitemapPolicyManager uses the policy sitemap to resolve the policy
for a certain URL.</p>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/accesscontrol/accreditablemanagers.xml
Index: accreditablemanagers.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Accreditable Managers</title>
<version/>
<type/>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Introduction</title>
<p>An AccreditableManager combines a UserManager, a GroupManager, an
IPRangeManager and a RoleManager.</p>
</section>
<section>
<title>UserManager</title>
<p>A UserManager manages users.</p>
</section>
<section>
<title>GroupManager</title>
<p>A GroupManager manages groups.</p>
</section>
<section>
<title>IPRangeManager</title>
<p>A IPRangeManager manages IP address rangess.</p>
</section>
<section>
<title>RoleManager</title>
<p>A RoleManager manages roles.</p>
</section>
</body>
</document>
1.1 cocoon-lenya/src/webapp/lenya/pubs/docs-new/content/xdocs/docs/components/accesscontrol/terms.xml
Index: terms.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Basic Terms</title>
<version/>
<type/>
<authors>
<person name="Andreas Hartmann" email="andreas@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Role</title>
<p>Roles are the connection between access control and CMS functionality. On
the access control side, you assign roles to users, IP address ranges and
groups at certain URL spaces. On the CMS side, you define which roles are
needed to execute certain usecases and workflow transitions.</p>
<p>Examples of roles are</p>
<ul>
<li>author</li>
<li>editor</li>
<li>admin</li>
</ul>
</section>
<section>
<title>Identifiable</title>
<p>An Identifiable is a characteristic of the client that can be identified.
Every Identifiable is Accreditable. Lenya currently supports the following
identifiables:</p>
<ul>
<li>users</li>
<li>machines</li>
<li>the world (this idenitifiable is assigned to every client that tries to
access the system)</li>
</ul>
</section>
<section>
<title>Identity</title>
<p>An Identity is the collection of all Identifiables that have access to the
system in the current session. The identity always contains the world and
the machine that produced the request. If you logged in, the user is also
contained in the identity.</p>
<p>For instance, if you log in from the machine 192.168.0.16 as the user john,
your identity contains this machine, this user and the world.</p>
</section>
<section>
<title>Accreditable</title>
<p>An Accreditable can be accredited with roles at URLs. Lenya currently
supports the following accreditables:</p>
<ul>
<li>users</li>
<li>machines (accredition not implemented, use IP ranges instead)</li>
<li>IP address ranges</li>
<li>the world</li>
<li>groups</li>
</ul>
</section>
<section>
<title>Credential</title>
<p>A Credential assigns a set of Roles to an Accreditable, e.g.:</p>
<ul>
<li><code>news_editors: editor, reviewer</code> means "The group
<code>news_editors</code> has the roles <code>editor</code> and <code>
reviewer</code>."</li>
</ul>
</section>
<section>
<title>Policy</title>
<p>A Policy defines a set of Credentials for a certain URL. It has the
responsibility to return all Roles of an Accreditable at a certain URL.</p>
<p>If for instance the policy for the URL /tv/news contains the credentials</p>
<ul>
<li>
<code>news_editors: editor, reviewer</code>
</li>
<li>
<code>john: admin</code>
</li>
<li>
<code>192.168.0.72: visitor</code>
</li>
</ul>
<p>and user <code>john</code> belongs to the group <code>news_editors</code>
and has logged in from the machine <code>192.168.0.72</code>, the policy
returns the role set <code>editor, reviewer, admin, visitor</code> for the
accreditable <code>john</code>.</p>
<p>A policy may not contain invalid accreditables. E.g., if a user is deleted
and another user with the same ID is created, he may not get the same
privileges as the former one.</p>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-cvs-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-cvs-help@cocoon.apache.org