Author: smumford
Date: 2010-05-12 08:07:57 -0400 (Wed, 12 May 2010)
New Revision: 3065
Modified:
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml
Log:
JBEPP-276: Minor copy edits
Modified:
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml
===================================================================
---
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml 2010-05-12
07:59:24 UTC (rev 3064)
+++
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml 2010-05-12
12:07:57 UTC (rev 3065)
@@ -5,16 +5,16 @@
]>
<chapter id="chap-Reference_Guide-Foundations">
<title>Foundations</title>
- <section id="sect-Reference_Guide-Foundations-GateIn_Kernel">
- <title>GateIn Kernel</title>
+ <section id="sect-Reference_Guide-Foundations-The_GateIn_Kernel">
+ <title>The GateIn Kernel</title>
<para>
&PRODUCT; is built as a set of services on top of a dependency injection kernel.
The kernel provides configuration, lifecycle handling, component scopes, and some core
services.
</para>
<para>
- Service components exist in two scopes. First scope is represented by <emphasis
role="bold">RootContainer</emphasis> - it contains services that exist
independently of any portal, and can be accessed by all portals.
+ Service components exist in two scopes. The first scope is represented by the
<emphasis role="bold">RootContainer</emphasis>. It contains services
that exist independently of any portal, and can be accessed by all portals.
</para>
<para>
- Second scope is portal-private in the form of <emphasis
role="bold">PortalContainer</emphasis>. Each portal lives in an
instance of PortalContainer. This scope contains services that are common for a set of
portals, and services which should not be shared by all portals.
+ The second scope, the <emphasis
role="bold">PortalContainer</emphasis>, is portal-private. Each portal
exists in an instance of PortalContainer. This scope contains services that are common for
a set of portals, and services which should not be shared by all portals.
</para>
<para>
<mediaobject>
@@ -27,21 +27,35 @@
</mediaobject>
</para>
<para>
- Whenever a specific service is looked up through PortalContainer, and the service is
not available, the lookup is delegated further up to RootContainer. We can therefore have
default instance of a certain component in RootContainer, and portal specific instances in
some or all PortalContainers, that override the default instance.
+ Whenever a specific service is looked up through PortalContainer, and the service is
not available, the lookup is delegated further up to RootContainer.
</para>
<para>
- Whenever your portal application has to be integrated more closely with GateIn
services, the way to do it is by looking up these services through PortalContainer. Be
careful though - only officially documented services should be accessed this way, and used
according to documentation, as most of the services are an implementation detail of
GateIn, and subject to change without notice.
+ Therefore &PRODUCT; can have default instance of a certain component in
RootContainer, and portal specific instances in some or all PortalContainers, that
override the default instance.
</para>
+ <para>
+ Whenever your portal application has to be integrated more closely with GateIn
services, these services can be looked up through PortalContainer.
+ </para>
+ <important>
+ <para>
+ Only officially documented services should be accessed this way, and used according
to documentation, as most of the services are an implementation detail of GateIn, and
subject to change without notice.
+ </para>
+ </important>
</section>
<section id="sect-Reference_Guide-Foundations-Configuring_services">
<title>Configuring services</title>
<para>
- GateIn Kernel uses dependency injection to create services based on <emphasis
role="bold">configuration.xml</emphasis> configuration files. The
location of the configuration files determines if services are placed into RootContainer
scope, or into PortalContainer scope. All configuration.xml files located at <emphasis
role="bold">conf/configuration.xml</emphasis> in the classpath (any
directory, or any jar in the classpath) will have their services configured at
RootContainer scope. All configuration.xml files located at <emphasis
role="bold">conf/portal/configuration.xml</emphasis> in the classpath
will have their services configured at PortalContainer scope. Additionally, <emphasis
role="bold">portal extensions</emphasis> can contain configuration in
<emphasis role="bold">WEB-INF/conf/configuration.xml</emphasis>, and
will also have their services configured at PortalContainer scope.
+ GateIn Kernel uses dependency injection to create services based on
<filename>configuration.xml</filename> configuration files. The location of
the configuration files determines if services are placed into RootContainer scope, or
into PortalContainer scope.
</para>
+ <para>
+ All <filename>configuration.xml</filename> files located at
<emphasis>conf/configuration.xml</emphasis> in the classpath (any directory,
or any jar in the classpath) will have their services configured at RootContainer scope.
All <filename>configuration.xml</filename> files located at <emphasis
role="bold">conf/portal/configuration.xml</emphasis> in the classpath
will have their services configured at PortalContainer scope.
+ </para>
+ <para>
+ Additionally, <emphasis role="bold">portal extensions</emphasis>
can contain configuration in
<filename>WEB-INF/conf/configuration.xml</filename>, and will also have their
services configured at PortalContainer scope.
+ </para>
<note>
<para>
- Portal extensions are described later on.
+ Portal extensions are described later in this document.
</para>
</note>
</section>
@@ -51,10 +65,10 @@
<section id="sect-Reference_Guide-Configuration_syntax-Components">
<title>Components</title>
<para>
- A service component is defined in <emphasis
role="bold">configuration.xml</emphasis> by using <emphasis
role="bold"><component></emphasis> element.
+ A service component is defined in <filename>configuration.xml</filename>
by using <emphasis role="bold"><component></emphasis>
element.
</para>
<para>
- There is only one required information when defining a service - the service
implementation class, specified using <emphasis
role="bold"><type></emphasis>
+ Only one piece of information is required when defining a service; the service
implementation class. This is specified using <emphasis
role="bold"><type></emphasis>
</para>
<para>
Every component has a <emphasis
role="bold"><key></emphasis> that identifies it. If not
explicitly set, a key defaults to the value of <type>. If key can be loaded
as a class, a Class object is used as a key, otherwise a String is used.
@@ -62,101 +76,107 @@
<para>
The usual approach is to specify an interface as a key.
</para>
- <example
id="exam-Reference_Guide-Components-Example_of_service_component_configuration">
- <title>Example of service component configuration:</title>
-
-<programlisting role="XML">
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<configuration
+<!-- TODO XML highlight once issue
https://bugzilla.redhat.com/show_bug.cgi?id=590933
resolved-->
+<programlisting ><![CDATA[<?xml version="1.0"
encoding="ISO-8859-1"?>
+<configuration
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd
http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"
-
xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">
- <component>
-
<key>org.exoplatform.services.database.HibernateService</key>
-
<type>org.exoplatform.services.database.impl.HibernateServiceImpl</type>
+
xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">
+ <component>
+ <key>org.exoplatform.services.database.HibernateService</key>
+
<type>org.exoplatform.services.database.impl.HibernateServiceImpl</type>
...
- </component>
-</configuration>
-</programlisting>
- </example>
+ </component>
+</configuration>]]></programlisting>
+
</section>
<section
id="sect-Reference_Guide-Configuration_syntax-External_Plugins">
<title>External Plugins</title>
<para>
- GateIn Kernel supports non-component objects that can be configured, instantiated,
and injected into registered components, using method calls. The mechanism is called
'plugins', and allows portal extensions to add additional configurations to core
services.
+ The GateIn Kernel supports non-component objects that can be configured,
instantiated, and injected into registered components, using method calls. This
'plugins' method allows portal extensions to add additional configurations to core
services.
</para>
<para>
- External plugin is defined by using <emphasis
role="bold"><external-component-plugins></emphasis>
wrapper element which contains one or more <emphasis
role="bold"><component-plugin></emphasis> definitions.
<external-component-plugins> uses <emphasis
role="bold"><target-component></emphasis> to specify a
target service component that will receive injected objects.
+ An external plugin is defined by using the
<literal><external-component-plugins></literal> wrapper element
which contains one or more <literal><component-plugin></literal>
definitions.
</para>
<para>
- Every <component-plugin> defines an implementation type, and a method
on target component to use for injection (<emphasis
role="bold"><set-method></emphasis>).
+ The <literal><external-component-plugins></literal> element
uses <literal><target-component></literal> to specify a target
service component that will receive injected objects.
</para>
<para>
- A plugin implementation class has to implement <emphasis
role="bold">org.exoplatform.container.component.
ComponentPlugin</emphasis> interface.
+ Every <literal><component-plugin></literal> defines an
implementation type, and a method on target component to use for injection
(<literal><set-method></literal>).
</para>
<para>
- In the following example <emphasis
role="bold">PortalContainerDefinitionPlugin</emphasis> implements
ComponentPlugin:
+ A plugin implementation class has to implement the <emphasis
role="bold">org.exoplatform.container.component.
ComponentPlugin</emphasis> interface.
</para>
- <example
id="exam-Reference_Guide-External_Plugins-PortalContainerDefinitionPlugin">
- <title>PortalContainerDefinitionPlugin</title>
-
-<programlisting role="XML">
-<?xml version="1.0" encoding="UTF-8"?>
-<configuration
+ <para>
+ In the following example
<literal>PortalContainerDefinitionPlugin</literal> implements
<literal>ComponentPlugin</literal>:
+ </para>
+<!-- TODO XML highlight once issue
https://bugzilla.redhat.com/show_bug.cgi?id=590933
resolved-->
+<programlisting><![CDATA[<?xml version="1.0"
encoding="UTF-8"?>
+<configuration
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd
http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"
-
xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">
+
xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">
- <external-component-plugins>
-
<target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
- <component-plugin>
- <!-- The name of the plugin -->
- <name>Add PortalContainer Definitions</name>
+ <external-component-plugins>
+
<target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
+ <component-plugin>
+ <!-- The name of the plugin -->
+ <name>Add PortalContainer Definitions</name>
- <!-- The name of the method to call on the PortalContainerConfig
- in order to register the PortalContainerDefinitions -->
- <set-method>registerPlugin</set-method>
+ <!-- The name of the method to call on the PortalContainerConfig
+ in order to register the PortalContainerDefinitions -->
+ <set-method>registerPlugin</set-method>
- <!-- The fully qualified name of the PortalContainerDefinitionPlugin
-->
-
<type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type>
+ <!-- The fully qualified name of the PortalContainerDefinitionPlugin -->
+
<type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type>
...
- </component-plugin>
- </external-component-plugins>
-</configuration>
-</programlisting>
- </example>
+ </component-plugin>
+ </external-component-plugins>
+</configuration>]]></programlisting>
+
</section>
<section
id="sect-Reference_Guide-Configuration_syntax-Includes_and_special_URLs">
<title>Includes, and special URLs</title>
<para>
- It is possible to break <emphasis
role="bold">configuration.xml</emphasis> file into many smaller files,
that are then included into a 'master' configuration file. The included files are
complete configuration xml documents by themselves - they are not fragments of text.
+ It is possible to the break <filename>configuration.xml</filename> file
into many smaller files, that are then included into a 'master' configuration
file.
</para>
<para>
- An example configuration.xml that 'outsources' its content into several
files:
+ The included files must be complete
<filename>configuration.xml</filename> documents in themselves. That is, they
can not be fragments of text.
</para>
-
-<programlisting role="XML">
-<configuration
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ <para>
+ Below is an example <filename>configuration.xml</filename> that
'outsources' its content into several files:
+ </para>
+ <programlistingco>
+ <areaspec>
+ <area coords="6"
id="area-Reference_Guide-Configuration_syntax-Includes_and_special_URLs-url_schema"
/>
+ </areaspec>
+<!-- TODO XML highlight once issue
https://bugzilla.redhat.com/show_bug.cgi?id=590933
resolved-->
+<programlisting><![CDATA[<configuration
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd
http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"
-
xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">
+
xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">
-
<import>war:/conf/sample-ext/jcr/jcr-configuration.xml</import>
-
<import>war:/conf/sample-ext/portal/portal-configuration.xml</import>
+ <import>war:/conf/sample-ext/jcr/jcr-configuration.xml</import>
+ <import>war:/conf/sample-ext/portal/portal-configuration.xml</import>
-</configuration>
-</programlisting>
+</configuration>]]></programlisting>
+ <calloutlist>
+ <callout
arearefs="area-Reference_Guide-Configuration_syntax-Includes_and_special_URLs-url_schema">
+
<para>
- We see a special URL being used to reference another configuration file. URL schema
<emphasis role="bold">'war:'</emphasis> means, that the path
that follows is resolved relative to current PortalContainer's servlet context
resource path, starting at <emphasis role="bold">WEB-INF</emphasis>
as a root.
+ This line is being used to reference another configuration file. The
<literal>war:</literal> URL schema indicates that the path that follows is to
be resolved relative to the current PortalContainer's servlet context resource path,
starting with <emphasis role="bold">WEB-INF</emphasis> as a root.
</para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
<note>
<para>
Current PortalContainer is really a newly created PortalContainer, as war: URLs only
make sense for PortalContainer scoped configuration.