From do-not-reply at jboss.org Fri Feb 19 16:30:06 2010 Content-Type: multipart/mixed; boundary="===============5278775166984642386==" MIME-Version: 1.0 From: do-not-reply at jboss.org To: exo-jcr-commits at lists.jboss.org Subject: [exo-jcr-commits] exo-jcr SVN: r1932 - in jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules: kernel and 1 other directory. Date: Fri, 19 Feb 2010 16:30:05 -0500 Message-ID: <201002192130.o1JLU57U015617@svn01.web.mwc.hst.phx2.redhat.com> --===============5278775166984642386== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: nfilotto Date: 2010-02-19 16:30:05 -0500 (Fri, 19 Feb 2010) New Revision: 1932 Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/config= uration.xml Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml Log: EXOJCR-528: Documentation in Docbook added = Added: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/co= nfiguration.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/confi= guration.xml (rev 0) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel/confi= guration.xml 2010-02-19 21:30:05 UTC (rev 1932) @@ -0,0 +1,750 @@ + + + + Configuration + +
+ Kernel configuration namespace + + To be effective the namespace URI http://www.exoplaform.org/xml/ns/kernel_1_1.xsd= must + be target namespace of the XML configuration file. + + <xsd:schema + targetNamespace=3D"http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" + xmlns=3D"http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" + xmlns:xsd=3D"http://www.w3.org/2001/XMLSchema" + elementFormDefault=3D"qualified" + attributeFormDefault=3D"unqualified" + version=3D"1.0"> + + ... +</xsd:schema> +
+ +
+ Understanding How configuration files are loaded + +
+ First concepts + + You can find the first concepts of How are the + configuration files loaded here. +
+ +
+ Advanced concepts for the <emphasis>PortalContainers</emphasi= s> + + + Since eXo JCR 1.12, we added a set of new features that have b= een + designed to extend portal applications such as GateIn. + +
+ Add new configuration files from a WAR file + + A ServletContextListener called + org.exoplatform.container.web.PortalContainerConfigOwner + has been added in order to notify the application that a given web + application provides some configuration to the portal container, a= nd + this configuration file is the file + WEB-INF/conf/configuration.xml available in t= he + web application itself. + + If your war file contains some configuration to add to the + PortalContainer simply add the following lines in y= our + web.xml file. + + <?xml version=3D"1.0" encoding=3D"ISO-8859-1" ?= > +<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Applicatio= n 2.3//EN" + "http://java.sun.com/dtd/web-app_2_3.dtd"> +<web-app> +... + <!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --> + <!-- LISTENER = --> + <!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --> + <listener> + <listener-class>org.exoplatform.container.web.PortalContainerCon= figOwner</listener-class> + </listener> +... +</web-app> +
+ +
+ Create your <emphasis>PortalContainers</emphasis> from a WAR + file + + A ServletContextListener called + org.exoplatform.container.web.PortalContainerCreator + has been added in order to create the current portal containers th= at + have been registered. We assume that all the web applications have + already been loaded before calling + PortalContainerCreator.contextInitialized. + + + In GateIn, the PortalContainerCreator is + already managed by the file + starter.war/ear. + +
+ +
+ Define a <emphasis>PortalContainer</emphasis> with its + dependencies and its settings + + Now we can define precisely a portal container and its + dependencies and settings thanks to the + PortalContainerDefinition that currently contains t= he + name of the portal container, the name of the rest context, the na= me + of the realm he web application dependencies ordered by loading + priority (i.e. the first dependency must be loaded at first and so + on..) and the settings. + + To be able to define a PortalContainerDefinition, + we need to ensure first of all that a + PortalContainerConfig has been defined at the + RootContainer level, see below an example: + + <component> + <!-- The full qualified name of the PortalContainerConfig --> + <type>org.exoplatform.container.definition.PortalContainerConfig= </type> + <init-params> + <!-- The name of the default portal container --> + <value-param> + <name>default.portal.container</name> + <value>myPortal</value> + </value-param> + <!-- The name of the default rest ServletContext --> + <value-param> + <name>default.rest.context</name> + <value>myRest</value> + </value-param> + <!-- The name of the default realm --> + <value-param> + <name>default.realm.name</name> + <value>my-exo-domain</value> + </value-param> + </init-params> + </component> + + + Descriptions of the fields of + <envar>PortalContainerConfig</envar> + + + + + default.portal.container + + The name of the default portal container. This fiel= d is + optional. + + + + default.rest.context + + The name of the default rest + ServletContext. This field is optional. + + + + default.realm.name + + The name of the default realm. This field is + optional. + + + +
+ + A new PortalContainerDefinition can be defin= ed + at the RootContainer level thanks to an external + plugin, see below an example: <external-compon= ent-plugins> + <!-- The full qualified name of the PortalContainerConfig --> + <target-component>org.exoplatform.container.definition.PortalCon= tainerConfig</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 full qualified name of the PortalContainerDefinitionPlug= in --> + <type>org.exoplatform.container.definition.PortalContainerDefi= nitionPlugin</type> + <init-params> + <object-param> + <name>portal</name> + <object type=3D"org.exoplatform.container.definition.PortalCo= ntainerDefinition"> + <!-- The name of the portal container --> + <field name=3D"name"> + <string>myPortal</string> + </field> + <!-- The name of the context name of the rest web applicati= on --> + <field name=3D"restContextName"> + <string>myRest</string> + </field> + <!-- The name of the realm --> + <field name=3D"realmName"> + <string>my-domain</string> + </field> + <!-- All the dependencies of the portal container ordered b= y loading priority --> + <field name=3D"dependencies"> + <collection type=3D"java.util.ArrayList"> + <value> + <string>foo</string> + </value> + <value> + <string>foo2</string> + </value> + <value> + <string>foo3</string> + </value> + </collection> + </field> + <!-- A map of settings tied to the portal container --> + <field name=3D"settings"> + <map type=3D"java.util.HashMap"> + <entry> + <key> + <string>foo</string> + </key> + <value> + <string>value</string> + </value> + </entry> + <entry> + <key> + <string>int</string> + </key> + <value> + <int>10</int> + </value> + </entry> + <entry> + <key> + <string>long</string> + </key> + <value> + <long>10</long> + </value> + </entry> + <entry> + <key> + <string>double</string> + </key> + <value> + <double>10</double> + </value> + </entry> + <entry> + <key> + <string>boolean</string> + </key> + <value> + <boolean>true</boolean> + </value> + </entry> = + </map> + </field> = + <!-- The path to the external properties file --> + <field name=3D"externalSettingsPath"> + <string>classpath:/org/exoplatform/container/definitio= n/settings.properties</string> + </field> + </object> + </object-param> + </init-params> + </component-plugin> + </external-component-plugins> + + + Descriptions of the fields of + <envar>PortalContainerDefinition</envar> + + + + + name + + The name of the portal container. This field is + mandatory. + + + + restContextName + + The name of the context name of the rest web + application. This field is optional. The default value will + the value define at the PortalContainerConfig + level if it is not null, "rest" otherwise. + + + + realmName + + The name of the realm. This field is optional. The + default value will the value define at the + PortalContainerConfig level if it is not nu= ll, + "exo-domain" otherwise. + + + + dependencies + + All the dependencies of the portal container ordere= d by + loading priority. The dependencies are in fact the list of= the + context names of the web applications from which the portal + container depends. This field is optional. The dependency + order is really crucial since it will be interpreted the s= ame + way by several components of the platform. All those + components, will consider the 1st element in the list less + important than the second element and so on. It is current= ly + used to: + + Know the loading order of all the + dependencies. + + + + If we have several + PortalContainerConfigOwner + + The ServletContext of all= the + PortalContainerConfigOwner will= be + unified, if we use the unified + ServletContext + (PortalContainer.getPortalContext()<= /emphasis>) + to get a resource, it will try to get the reso= urce + in the ServletContext of the mo= st + important PortalContainerConfigOwner + (i.e. last in the dependency list) and if it c= ans + find it, it will try with the second most impo= rtant + PortalContainerConfigOwner and = so + on. + + + + The ClassLoader of all the + PortalContainerConfigOwner will= be + unified, if we use the unified + ClassLoader + (PortalContainer.getPortalClassLoade= r()) + to get a resource, it will try to get the reso= urce + in the ClassLoader of the most + important PortalContainerConfigOwner + (i.e. last in the dependency list) and if it c= ans + find it, it will try with the second most impo= rtant + PortalContainerConfigOwner and = so + on. + + + + + + + + settings + + A java.util.Map of internal paramete= rs + that we would like to tie the portal container. Those + parameters could have any type of value. This field is + optional. + + + + externalSettingsPath + + The path of the external properties file to load as + default settings to the portal container. This field is + optional. The external properties files can be either of t= ype + "properties" or of type "xml". The path will be interprete= d as + follows: + + The path doesn't contain any prefix of type + "classpath:", "jar:" or "file:", we assume that the = file + could be externalized so we apply the following + rules: + + A file exists at + ${exo-conf-dir}/portal/${portalConta= inerName}/${externalSettingsPath}, + we will load this file. + + + + No file exists at the previous path, we = then + assume that the path cans be interpreted by the + ConfigurationManager. + + + + + + The path contains a prefix, we then assume that + the path cans be interpreted by the + ConfigurationManager. + + + + + +
+ + Internal and external settings are both optional, but if we = give + a non empty value for both the application will merge the settings= . If + the same setting name exists in both settings, we apply the follow= ing + rules: + + + + The value of the external setting is + null, we ignore the value. + + + + The value of the external setting is not + null and the value of the internal settin= g is + null, the final value will be the external + setting value that is of type String. + + + + Both values are not null, we will have to + convert the external setting value into the target type which = is + the type of the internal setting value, thanks to the static + method valueOf(String), the following + sub-rules are then applied: + + + + The method cannot be found, the final value will be = the + external setting value that is of type + String. + + + + The method can be found and the external setting val= ue + is an empty String, we ignore the external + setting value. + + + + The method can be found and the external setting val= ue + is not an empty String but the method call + fails, we ignore the external setting value. + + + + The method can be found and the external setting val= ue + is not an empty String and the method call + succeeds, the final value will be the external setting val= ue + that is of type of the internal setting value. + + + + +
+ +
+ <envar>PortalContainer</envar> settings + + We can inject the value of the portal container settings into + the portal container configuration files thanks to the variables w= hich + name start with "portal.container.", so to get + the value of a setting called "foo" just use = the + following syntax ${portal.container.foo}. You= can + also use internal variables, such as: + + + Definition of the internal variables + + + + + portal.container.name + + Gives the name of the current portal container. + + + + portal.container.rest + + Gives the context name of the rest web application = of + the current portal container. + + + + portal.container.realm + + Gives the realm name of the current portal + container. + + + +
+ + You can find below an example of how to use the + variables:<configuration xmlns:xsi=3D"http://ww= w.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=3D"http://www.exoplafo= rm.org/xml/ns/kernel_1_1.xsd http://www.exoplaform.org/xml/ns/kernel_1_1.xs= d" + xmlns=3D"http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"> + <component> + <type>org.exoplatform.container.TestPortalContainer$MyComponent&= lt;/type> + <init-params> + <!-- The name of the portal container --> + <value-param> + <name>portal</name> + <value>${portal.container.name}</value> + </value-param> + <!-- The name of the rest ServletContext --> + <value-param> + <name>rest</name> + <value>${portal.container.rest}</value> + </value-param> + <!-- The name of the realm --> + <value-param> + <name>realm</name> + <value>${portal.container.realm}</value> + </value-param> + <value-param> + <name>foo</name> + <value>${portal.container.foo}</value> + </value-param> + <value-param> + <name>before foo after</name> + <value>before ${portal.container.foo} after</value> + </value-param> + </init-params> + </component> +</configuration> +
+
+
+ +
+ System property configuration + + A new property configurator service has been developed for taking + care of configuring system properties from the inline kernel configura= tion + or from specified property files. + + The services is scoped at the root container level because it is + used by all the services in the different portal containers in the + application runtime. + +
+ Properties init param + + The properties init param takes a property declared to configu= re + various properties. + + <component> + <key>PropertyManagerConfigurator</key> + <type>org.exoplatform.container.PropertyConfigurator</type> + <init-params> + <properties-param> + <name>properties</name> + <property name=3D"foo" value=3D"bar"/> + </properties-param> + </init-params> +</component> +
+ +
+ Properties URL init param + + The properties URL init param allow to load an external file by + specifying its URL. Both property and XML format are supported, see = the + javadoc of the java.util.Properties + class for more information. When a property file is loaded the vario= us + property declarations are loaded in the order in which the properties + are declared sequentially in the file. + + <component> + <key>PropertyManagerConfigurator</key> + <type>org.exoplatform.container.PropertyConfigurator</type> + <init-params> + <value-param> + <name>properties.url</name> + <value>classpath:configuration.properties</value> + </value-param> + </init-params> +</component> +
+ +
+ System Property configuration of the properties URL + + It is possible to replace the properties URL init param by a + system property that overwrites it. The name of that property is + exo.properties.url. +
+
+ +
+ Runtime configuration profiles + + The kernel configuration is able to handle configuration profile= s at + runtime (as opposed to packaging time). + +
+ Profiles activation + + An active profile list is obtained during the boot of the root + container and is composed of the system property + exo.profiles sliced according the "," delimiter= and + also a server specific profile value (tomcat for tomcat, jboss for + jboss, etc...). + + # runs GateIn on Tomcat with the profiles tomcat and= foo +sh gatein.sh -Dexo.profiles=3Dfoo + +# runs GateIn on JBoss with the profiles jboss, foo and bar +sh run.sh -Dexo.profiles=3Dfoo,bar +
+ +
+ Profiles configuration + + Profiles are configured in the configuration files of the eXo + kernel. + +
+ Profiles definition + + Profile activation occurs at XML to configuration object + unmarshalling time. It is based on an "profile" attribute that is + present on some of the XML element of the configuration files. To + enable this the kernel configuration schema has been upgraded to + kernel_1_1.xsd. The configuration is based on the following + rules: + + + + Any kernel element with the no profiles + attribute will create a configuration object + + + + Any kernel element having a profiles + attribute containing at least one of the active profiles will + create a configuration object + + + + Any kernel element having a profiles + attribute matching none of the active profile will not create a + configuration object + + + + Resolution of duplicates (such as two components with sa= me + type) is left up to the kernel + + +
+ +
+ Profiles capable configuration elements + + A configuration element is profiles cap= able + when it carries a profiles element. + +
+ Component element + + The component element declares a component when activated.= It + will shadow any element with the same key declared before in the + same configuration file: + + <component> + <key>Component</key> + <type>Component</type> +</component> + +<component profile=3D"foo"> + <key>Component</key> + <type>FooComponent</type> +</component> +
+ +
+ Import element + + The import element imports a referenced configuration file + when activated: + + <import>empty</import> +<import profile=3D"foo">foo</import> +<import profile=3D"bar">bar</import> +
+ +
+ Init param element + + The init param element configures the parameter argument of + the construction of a component service: + + <component> + <key>Component</key> + <type>ComponentImpl</type> + <init-params> + <value-param> + <name>param</name> + <value>empty</value> + </value-param> + <value-param profile=3D"foo"> + <name>param</name> + <value>foo</value> + </value-param> + <value-param profile=3D"bar"> + <name>param</name> + <value>bar</value> + </value-param> + </init-params> +</component> +
+ +
+ Value collection element + + The value collection element configures one of the value of + collection data: + + <object type=3D"org.exoplatform.container.con= figuration.ConfigParam"> + <field name=3D"role"> + <collection type=3D"java.util.ArrayList"> + <value><string>manager</string></value> + <value profile=3D"foo"><string>foo_manager</string>= ;</value> + <value profile=3D"foo,bar"><string>foo_bar_manager</s= tring></value> + </collection> + </field> +</object> +
+ +
+ Field configuration element + + The field configuration element configures the field of an + object: + + <object-param> + <name>test.configuration</name> + <object type=3D"org.exoplatform.container.configuration.ConfigParam"&= gt; + <field name=3D"role"> + <collection type=3D"java.util.ArrayList"> + <value><string>manager</string></value> + </collection> + </field> + <field name=3D"role" profile=3D"foo,bar"> + <collection type=3D"java.util.ArrayList"> + <value><string>foo_bar_manager</string></valu= e> + </collection> + </field> + <field name=3D"role" profile=3D"foo"> + <collection type=3D"java.util.ArrayList"> + <value><string>foo_manager</string></value> + </collection> + </field> + </object> +</object-param> +
+
+
+
+ Modified: jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel= .xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml 2= 010-02-19 20:21:30 UTC (rev 1931) +++ jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml 2= 010-02-19 21:30:05 UTC (rev 1932) @@ -8,6 +8,9 @@ = + + = --===============5278775166984642386==--