raphael 2002/11/13 00:42:43
Added: xdocs registry.xml registry_syntax.xml registry_xml.xml
Log:
First draft of registry documentation
Revision Changes Path
1.1 jakarta-jetspeed/xdocs/registry.xml
Index: registry.xml
===================================================================
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
<title>Registry</title>
<subtitle>General overview</subtitle>
<authors>
<person name="Rapha�l Luta" email="[EMAIL PROTECTED]"/>
</authors>
</properties>
<body>
<section name="Overview">
<p>
The Registry stores most of dynamically configurable elemnts you can add to
the engine.
Among these elements, you'll find the list of available portlets, the layout
elements
definitions and the known client defintions
</p>
<p>
This registry uses the pluggable Turbien service architecture so that you can
select from
different implementations depending on your requirements. There are currently
2 available
implementations by default:
</p>
<ul>
<li><a href="registry_xml.html">a XML file based implementation</a></li>
<li>an OJB based, SQL database driven implementation</li>
</ul>
<p>
This document will present the different elements encountered in the registry
and the
base API.
</p>
</section>
<section name="Elements of the Registry">
<p>
Currently the Registry can store 7 different types of elements used within the
Jetspeed engine
</p>
<table>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
<tr>
<td>
<p><strong>Portlets</strong></p>
<a href="registry_syntax.html#Portlet">View XML syntax</a>
</td>
<td>
The basic elements to store within Registry are the portlet definitions that
define
which components are available to be placed on the users portal pages.
</td>
</tr>
<tr>
<td>
<p><strong>Controls</strong></p>
<a href="registry_syntax.html#Control">View XML syntax</a>
</td>
<td>
The controls are the elements of the global layout that decorate a portlet
on a page
and provides access to the portal actions defined for the portlet, like
customization.
Only controls defined the Registry can be used in the user pages.
<p>
For more information on controls, check out the <a href="">Jetspeed Layout
overview</a>.
</p>
</td>
</tr>
<tr>
<td>
<p><strong>Controllers</strong></p>
<a href="registry_syntax.html#Controller">View XML syntax</a>
</td>
<td>
The controllers define how the portlets are displayed on a portal page (in
columns, panes
, etc...) and allow more or less sophisticated customization of a user page.
By default, all the controllers defined in the registry are available for
users to customize
their page layout.
<p>
For more information on controllers, check out the <a href="">Jetspeed
Layout overview</a>.
</p>
</td>
</tr>
<tr>
<td>
<p><strong>Skins</strong></p>
<a href="registry_syntax.html#Skin">View XML syntax</a>
</td>
<td>
The skins define the color schemes used by the portal on a specific user
page (or part
of a page)
<p>
For more information on skins, check out the <a href="">Jetspeed Layout
overview</a>.
</p>
</td>
</tr>
<tr>
<td>
<p><strong>Media Types</strong></p>
<a href="registry_syntax.html#Media">View XML syntax</a>
</td>
<td>
The media-types define the different variations of markup rendering
supported by
this specific instance of Jetspeed. Working in cunjunction with the Clients
defintion,
it enables you to control how the different user-agents access your portal
<p>
For more information on client handling, check out the <a href="">Client
detection</a>.
</p>
</td>
</tr>
<tr>
<td>
<p><strong>Clients</strong></p>
<a href="registry_syntax.html#Client">View XML syntax</a>
</td>
<td>
The clients definitions entries are used to describe user agent capabilities
and in
cunjunction with Media types information define how the clients access the
portal
<p>
For more information on client handling, check out the <a href="">Client
detection</a>.
</p>
</td>
</tr>
<tr>
<td>
<p><strong>Security</strong></p>
<a href="registry_syntax.html#Client">View XML syntax</a>
</td>
<td>
The security entries define standard set of permissions that can be
associated to
page elements and portal actions to protect their access.
<p>
For more information, check out the <a href="security.html">Security</a>
information.
</p>
</td>
</tr>
</table>
</section>
<section name="Administrating the Registry">
<p>
Currently, there are no complete GUI for administrating the registry elements
in Jetspeed,
you can only browse the contents of the different registries by using the
<a href="administration.html">administration console</a>. In most case you'll
currently need to
use implementation specific ways to manipulate your entries, like editing the
XML files
directly.
</p>
<p>
An effort is currently underway to create complete administration tools for
registry
manipulation, so watch
<a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=11738";>this
space</a> !
</p>
</section>
<section name="Registry API">
<p>
The Registry system has a very simple API, based on one Turbine service and an
interface based object model.
</p>
<subsection name="Object Model">
<p>The object model API is defined in the following package:</p>
<source>
org.apache.jetspeed.om.registry
</source>
<p>
This API defines the operations available on the different registries as
well as the
the structure of of the object stored within them. The <code>Registry</code>
and
<code>RegistryEntry</code> interfaces define the standard methods of a
registry or an entry.
</p>
<p>
For some registries, sub-interfaces declare additionnal methods that are
only meaningful for
a specific type of entry. For example the <code>ClientRegistry</code>
interface adds the
capacity to search for a specific entry matching a given capability.
</p>
<p>
A default implementation of this object model can be found in the base
subpackage of the
registry object model. This implementation is used by the XML Registry
service implementation.
</p>
</subsection>
<subsection name="Registry Service">
<p>
The <code>RegistryService</code> is a Turbine service that manages the
persistence of
the different registries and instanciates them. A commodity static facade is
provided
to simplify access to this service.
</p>
<source>
Registry service package:
org.apache.jetspeed.services.registry
Registry service interface:
org.apache.jetspeed.services.registry.RegsitryService
Registry service facade:
org.apache.jetspeed.services.Registry
</source>
<p>
The <code>RegistryService</code> redefines several of the basic operations
of the
registry object model (add or remove entries) as a convenience to
</p>
<p>
For some registries, sub-interfaces declare additionnal methods that are
only meaningful for
a specific type of entry. For example the <code>ClientRegistry</code>
interface adds the
capacity to search for a specific entry matching a given capability.
</p>
</subsection>
<subsection name="Examples">
<p>
Here are some code fragments on how to use the registry service for basic
operations
</p>
<source>
import org.apache.jetspeed.services.registry.Registry;
import org.apache.jetspeed.om.registry.PortletRegistry;
import org.apache.jetspeed.om.registry.PortletEntry;
import org.apache.jetspeed.om.registry.RegistryException;
import org.apache.turbine.util.Log;
//create a new entry
PortletEntry myEntry = (PortletEntry)Registry.createEntry(Registry.PORTLET);
myEntry.setName("myEntry");
myEntry.setHidden(true);
myEntry.setType(PortletEntry.TYPE_INSTANCE);
myEntry.setClassname("com.mycompany.myportlet");
//Add it to the Registry
try
{
Registry.addEntry(Registry.PORTLET, myEntry);
}
catch (RegistryException e)
{
Log.error("Impossible to add entry in registry" + myEntry, e);
}
//Retrieve it and update
myEntry = (PortletEntry)Registry.getEntry(Registry.PORTLET, "myEntry");
myEntry.addParameter("_control", "ClearControl");
myEntry.addParameter("myParam", "myValue");
//Then delete it from registry
try
{
Registry.removeEntry(Registry.PORTLET, myEntry);
}
catch (RegistryException e)
{
Log.error("Impossible to remove entry from registry" + myEntry, e);
}
</source>
<p>
The <code>RegistryService</code> redefines several of the basic operations
of the
registry object model (add or remove entries) as a convenience to
</p>
<p>
For some registries, sub-interfaces declare additionnal methods that are
only meaningful for
a specific type of entry. For example the <code>ClientRegistry</code>
interface adds the
capacity to search for a specific entry matching a given capability.
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-jetspeed/xdocs/registry_syntax.xml
Index: registry_syntax.xml
===================================================================
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
<title>XML Registry syntax</title>
<subtitle>Markup syntax</subtitle>
<authors>
<person name="Rapha�l Luta" email="[EMAIL PROTECTED]"/>
</authors>
</properties>
<body>
<section name="XML Registry Syntax">
<p>
This document presents the XML syntax used by the default XML Registry
implementation.
</p>
</section>
<section name="Table of contents">
<ul>
<li><a href="#Registry">Registry</a></li>
<li><a href="#Portlet">Portlets</a></li>
<li><a href="#Control">Controls</a></li>
<li><a href="#Controller">Controllers</a></li>
<li><a href="#Skin">Skins</a></li>
<li><a href="#Media">Media Types</a></li>
<li><a href="#Client">Clients</a></li>
<li><a href="#Security">Security entries</a></li>
</ul>
</section>
<section name="Registry">
<p>
The registry element needs to be the root elements of any registry fragment.
It can contains any of the currently defined entries.
</p>
<source><![CDATA[
<!ELEMENT registry ( portlet-entry*,
portlet-control-entry*,
portlet-controller-entry*,
skin-entry*,
media-type-entry*,
client-entry*,
security-entry*
)>
<!ATTLIST registry
version CDATA "1.0">
]]></source>
</section>
<section name="Portlet">
<p>
The <code>portlet-entry</code> element
</p>
<source><![CDATA[
<!ELEMENT portlet-entry ( portlet-entry*,
portlet-control-entry*,
portlet-controller-entry*,
skin-entry*,
media-type-entry*,
client-entry*,
security-entry*
)>
]]></source>
</section>
<section name="Control">
<p>
The <code>portlet-control-entry</code> element
</p>
<source><![CDATA[
<!ELEMENT portlet-control-entry ( portlet-entry*,
portlet-control-entry*,
portlet-controller-entry*,
skin-entry*,
media-type-entry*,
client-entry*,
security-entry*
)>
]]></source>
</section>
<section name="Controller">
<p>
The <code>portlet-controller-entry</code> element
</p>
<source><![CDATA[
<!ELEMENT portlet-controller-entry ( portlet-entry*,
portlet-control-entry*,
portlet-controller-entry*,
skin-entry*,
media-type-entry*,
client-entry*,
security-entry*
)>
]]></source>
</section>
<section name="Skin">
<p>
The <code>skin-entry</code> element
</p>
<source><![CDATA[
<!ELEMENT skin-entry ( property+ )>
<!ATTLIST skin-entry
name ID #REQUIRED
hidden ( true | false ) "false" >
<!ELEMENT property EMPTY>
<!ATTLIST property
name CDATA #REQUIRED
value CDATA #REQUIRED
type (int | boolean | string | list) "string" >
]]></source>
</section>
<section name="Media">
<p>
The <code>media-type-entry</code> element
</p>
<source><![CDATA[
<!ELEMENT media-type-entry ( mime-type,
character-set?,
capability-map?
)>
<!ATTLIST media-type-entry
name ID #REQUIRED
hidden ( true | false ) "false" >
<!ELEMENT mime-type CDATA>
<!ELEMENT character-set CDATA>
<!ELEMENT capability-map ( capability* )>
<!ELEMENT capability CDATA>
]]></source>
</section>
<section name="Client">
<p>
The <code>client-entry</code> element
</p>
<source><![CDATA[
<!ELEMENT client-entry ( user-agent-pattern,
manufacturer,
model,
version,
mimetype-map,
capability-map?
)>
<!ATTLIST client-entry
name ID #REQUIRED
hidden ( true | false ) "false" >
<!ELEMENT user-agent-pattern CDATA>
<!ELEMENT manufacturer CDATA>
<!ELEMENT model CDATA>
<!ELEMENT version CDATA>
<!ELEMENT mimetype-map ( mimetype+ )>
<!ELEMENT mimetype CDATA>
<!ELEMENT capability-map ( capability* )>
<!ELEMENT capability CDATA>
]]></source>
</section>
<section name="Security">
<p>
The <code>security-entry</code> element
</p>
<source><![CDATA[
<!ELEMENT security-entry ( meta-info?, access+ )>
<!ATTLIST security-entry
name ID #REQUIRED >
<!ELEMENT access (allow-if*, allow-if-owner? )>
<!ATTLIST access
action CDATA #REQUIRED >
<!ELEMENT allow-if EMPTY>
<!ATTLIST allow-if
role CDATA #REQUIRED >
<!ELEMENT allow-if-owner EMPTY>
]]></source>
<source><![CDATA[
<security-entry name="user-view_admin-all">
<meta-info>
<title>Users+V and Admin+C</title>
<description>Users view, Admin full access.</description>
</meta-info>
<access action="*">
<allow-if role="admin"/>
</access>
<access action="view">
<allow-if role="user"/>
</access>
</security-entry>
]]></source>
</section>
</body>
</document>
1.1 jakarta-jetspeed/xdocs/registry_xml.xml
Index: registry_xml.xml
===================================================================
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
<title>XML Registry</title>
<subtitle>Configuration and operation</subtitle>
<authors>
<person name="Rapha�l Luta" email="[EMAIL PROTECTED]"/>
</authors>
</properties>
<body>
<section name="XML Registry implementation">
<p>
This document presents information related to the default XML Registry
service
configuration and operation.
</p>
<p>
For a general description of the Registry usage and API, check the default
<a href="registry.html">Registry</a> presentation.
</p>
<p>
For a complete description of the XML syntax of the Registry, check the
<a href="registry_syntax.html">Registry XML Syntax</a> documentation.
</p>
</section>
<section name="Overview">
<p>
The XML Registry uses disk based XML files, called "Registry fragments", to
store
its different entries. Upon startup, it will load all the fragments it can
find as referenced by its configuration and populate dynamic memory based
Registries
of elements taht can be accessed through the Registry Service interface.
</p>
<p>
It will also periodically monitor the configured directory for any changes
in
the registry fragments or new fragments to load.
</p>
<p>
Finally, if any memory based Registries are changed because of some entries
are
added, set or removed programmatically, it will automatically save these
changes
<strong>before</strong> loading any fragments modified on disk. It will also
always save the
Registry state on shutdown.
</p>
</section>
<section name="Usage recommendation">
<p>
This registry is very easy to use because you can simply modify the XML
files on disk
and they will be automatically loaded without stopping Jetspeed. It's also
fast because
most of the work is entirely done is memory.
</p>
<p>
However, this implementation has 2 main limitations:
<ul>
<li>
it uses a lot of memory, especially if you define many entries through
syndication
</li>
<li>
it works only with a granularity of fragments and so may have some
issues if you
deal with online and offline entry simulatenous modifications that
affect the
same fragment.
</li>
</ul>
</p>
<p>
If any of these 2 limitations are a concern for you, we suggest that you use
the
SQL based OJB implementation.
</p>
</section>
<section name="Configuration">
<p>
The configuration of this implementation is very simple. Here's a copy of the
default configuration values in the JetspeedResources.properties file and a
detailed
table of configuration options.
</p>
<source>
#########################################
# Registry Service #
#########################################
services.Registry.classname=
org.apache.jetspeed.services.registry.CastorRegistryService
services.Registry.directory=/WEB-INF/conf/
services.Registry.mapping=/WEB-INF/conf/registry.xml
services.Registry.default.Portlet=local-portlets
services.Registry.default.PortletControl=local-managers
services.Registry.default.PortletController=local-managers
services.Registry.default.MediaType=local-medias
services.Registry.default.Skin=local-skins
services.Registry.default.Security=local-security
services.Registry.default.Client=local-clients
services.Registry.extension=.xreg
# Refresh rate, in seconds. 0 = no refresh. Min value = 60
services.Registry.refreshRate=300
</source>
<table>
<tr>
<th>Option</th>
<th>Descrption</th>
</tr>
<tr>
<td>services.Registry.classname</td>
<td>
<p><strong>Required</strong></p>
The name of the implementation to use for the Registry service
</td>
</tr>
<tr>
<td>services.Registry.directory</td>
<td>
<p><strong>Required</strong></p>
The directory where the registry needs to look for fragments
</td>
</tr>
<tr>
<td>services.Registry.extension</td>
<td>
<p><strong>Optional</strong><br /><strong>Default:</strong> .xreg</p>
All fragments that have this extension will be recognized by this
instance and loaded by the registry.
</td>
</tr>
<tr>
<td>services.Registry.refreshRate</td>
<td>
<p><strong>Optional</strong><br /><strong>Default:</strong> 300</p>
The number of seconds between disk refreshes. A value of 0 would mean
that
there will be no refresh. A hard coded minimum of 10 seconds has been
implemented to avoid unnecessary disk usage.
</td>
</tr>
<tr>
<td>services.Registry.mapping</td>
<td>
<p>
<strong>Optional</strong><br />
<strong>Default:</strong> ${webapp}/WEB-INF/conf/mapping.xml
</p>
The Castor mapping file that is used to load and save the XML files.<br
/>
<strong>
Do not change this file if you are unsure of what you are doing,
this may break your Jetspeed installation
</strong>
</td>
</tr>
<tr>
<td>services.Registry.default.Portlet</td>
<td>
<p><strong>Required</strong></p>
The fragment that will store new Portlet entries that have been added
programmatically.
</td>
</tr>
<tr>
<td>services.Registry.default.PortletControl</td>
<td>
<p><strong>Required</strong></p>
The fragment that will store new Control entries that have been added
programmatically.
</td>
</tr>
<tr>
<td>services.Registry.default.PortletController</td>
<td>
<p><strong>Required</strong></p>
The fragment that will store new Controller entries that have been added
programmatically.
</td>
</tr>
<tr>
<td>services.Registry.default.Skin</td>
<td>
<p><strong>Required</strong></p>
The fragment that will store new skin entries that have been added
programmatically.
</td>
</tr>
<tr>
<td>services.Registry.default.MediaType</td>
<td>
<p><strong>Required</strong></p>
The fragment that will store new media type entries that have been added
programmatically.
</td>
</tr>
<tr>
<td>services.Registry.default.Client</td>
<td>
<p><strong>Required</strong></p>
The fragment that will store new client entries that have been added
programmatically.
</td>
</tr>
<tr>
<td>services.Registry.default.Security</td>
<td>
<p><strong>Required</strong></p>
The fragment that will store new security entries that have been added
programmatically.
</td>
</tr>
<tr>
<td>services.Registry.verbose</td>
<td>
<p><strong>Optional</strong><br /><strong>Default:</strong> 0</p>
This option controls the amount of debugging output generated by the
regsitry if DEBUG logging mode is activated. 0 is minimum level and 3
is maximum verbosity. This is only useful for debugging purposes.
</td>
</tr>
</table>
</section>
<section name="Working with the registry">
<p>
This section presents some advices, tips and useful info for working with
the XML registry implementation.
</p>
<dl>
<dt><strong>Do not add new portlets to the standard files</strong></dt>
<dd>
<p>You should always create your own fragments, like the local-* fragments
defined in the configuration file. This will guarantee that your changes
won't be forgotten if you upgrade your installation.</p>
</dd>
<dt>
<strong>If you have both online and offline entry creations...</strong>
</dt>
<dd>
<p>You will save you a lot of headache by creating 2 local fragments, one
for
storing the entries added online, like the local-* fragments, and the other
for manual update, like manual-* fragments. This will greatly minimize the
risk of change collisions.</p>
</dd>
<dt>
<strong>Always shut down properly your application server</strong>
</dt>
<dd>
<p>Since the registry is auto-saved on shutdown, you should ensure that it
completes properly or risk registry corruption and data loss.
For production environment, a daily backup of the configuration files
through
a scheduled job is recommended to mitigate such risks.</p>
</dd>
<dt>
<strong>Fragments created by the feed daemon</strong>
</dt>
<dd>
<p>When using OCS syndication, the feed daemon will automatically create
and
rewrite fragments that with the syndicated entries.</p>
<p>These fragments have the following name convention:
feed_<feedname></p>
<p>Do not edit or modify these files as any changes will be lost when the
feed
daemon will next update the feed</p>
</dd>
</dl>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:jetspeed-dev-unsubscribe@;jakarta.apache.org>
For additional commands, e-mail: <mailto:jetspeed-dev-help@;jakarta.apache.org>
