1.4.2.2.3. Defining a PortalContainer with its dependencies and its settings

Warning

You are looking at documentation for an older release. Not what you want? See the current release documentation.

Now we can define precisely a portal container and its dependencies and settings thanks to the PortalContainerDefinition that currently contains the name of the portal container, the name of the rest context, the name of the realm, the web application dependencies ordered by loading priority (for example, the first dependency must be loaded at first and so on) and the settings.

To be able to define a PortalContainerDefinition, we first need to ensure that a PortalContainerConfig has been defined at the RootContainer level. See an example below:


  <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>

     <!-- Indicates whether the unregistered webapps have to be ignored -->

     <value-param>

        <name>ignore.unregistered.webapp</name>

        <value>true</value>

     </value-param>

      <!-- The default portal container definition -->

      <!-- It cans be used to avoid duplicating configuration -->

      <object-param>

        <name>default.portal.definition</name>

        <object type="org.exoplatform.container.definition.PortalContainerDefinition">

          <!-- All the dependencies of the portal container ordered by loading priority -->

          <field name="dependencies">

            <collection type="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 default portal container -->

          <field name="settings">

            <map type="java.util.HashMap">

              <entry>

                <key>

                  <string>foo5</string>

                </key>

                <value>

                  <string>value</string>

                </value>

              </entry>

              <entry>

                <key>

                  <string>string</string>

                </key>

                <value>

                  <string>value0</string>

                </value>

              </entry>

              <entry>

                <key>

                  <string>int</string>

                </key>

                <value>

                  <int>100</int>

                </value>

              </entry>

            </map>

          </field>

          <!-- The path to the external properties file -->

          <field name="externalSettingsPath">

            <string>classpath:/org/exoplatform/container/definition/default-settings.properties</string>

          </field>

        </object>

      </object-param>

    </init-params>

  </component>

default.portal.container (*)	The name of the default portal container. This field 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.
ignore.unregistered.webapp (*)	Indicates whether the unregistered webapps have to be ignored. If a webapp has not been registered as a dependency of any portal container, the application will use the value of this parameter to know what to do: If it is set to false, this webapp will be considered by default as a dependency of all the portal containers. If it is set to true, this webapp will not be considered by default as a dependency of any portal container, it will be simply ignored. This field is optional and this parameter is set to false by default.
default.portal.definition	The definition of the default portal container. This field is optional. The expected type is `org.exoplatform.container.definition.PortalContainerDefinition` that is described below. The parameters defined in this `PortalContainerDefinition` will be the default values.

Note

All the values of the parameters marked with a (*) can be set via System properties and also via variables loaded by the PropertyConfigurator. For example, in eXo Platform, it would be all the variables that can be defined via the exo.properties file. See Configuration overview for the exo.properties file.

A new PortalContainerDefinition can be defined at the RootContainer level thanks to an external plugin, see an example below:


  <external-component-plugins>

    <!-- The full qualified name of the PortalContainerConfig -->

    <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 full qualified name of the PortalContainerDefinitionPlugin -->

      <type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type>

      <init-params>

        <object-param>

          <name>portal</name>

          <object type="org.exoplatform.container.definition.PortalContainerDefinition">

            <!-- The name of the portal container -->

            <field name="name">

              <string>myPortal</string>

            </field>

            <!-- The name of the context name of the rest web application -->

            <field name="restContextName">

              <string>myRest</string>

            </field>

            <!-- The name of the realm -->

            <field name="realmName">

              <string>my-domain</string>

            </field>

            <!-- All the dependencies of the portal container ordered by loading priority -->

            <field name="dependencies">

              <collection type="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="settings">

              <map type="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="externalSettingsPath">

              <string>classpath:/org/exoplatform/container/definition/settings.properties</string>

            </field>

          </object>

        </object-param>

      </init-params>

    </component-plugin>

  </external-component-plugins>

See descriptions about fields of a PortalContainerDefinition when it is used to define a new portal container:

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 be defined at the `PortalContainerConfig` level.
realmName (*)	The name of the realm. This field is optional. The default value will be defined at the `PortalContainerConfig` level.
dependencies	All the dependencies of the portal container ordered by loading priority. This field is optional. The default value will be defined at the `PortalContainerConfig` level. The dependencies are in fact the list of the context names of the web applications from which the portal container depends. The dependency order is really crucial since it will be interpreted the same way by several components of the platform. All those components will consider the first element in the list less important than the second element and so on. It is currently 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 you use the unified `ServletContext` (PortalContainer.getPortalContext()) to get a resource, it will try to get the resource in the `ServletContext` of the most important `PortalContainerConfigOwner` (i.e. last in the dependency list). And if it does not find, it will try with the second most important `PortalContainerConfigOwner` and so on. The `ClassLoader` of all the `PortalContainerConfigOwner` will be unified, if we use the unified `ClassLoader` (PortalContainer.getPortalClassLoader()) to get a resource, it will try to get the resource in the `ClassLoader` of the most important `PortalContainerConfigOwner` (i.e. last in the dependency list) and if it can find it, it will try with the second most important `PortalContainerConfigOwner` and so on.
settings	A `java.util.Map` of internal parameters that we would like to tie the portal container. Those parameters could have any type of value. This field is optional. If some internal settings are defined at the `PortalContainerConfig` level, the two maps of settings will be merged. If a setting with the same name is defined in both maps, it will keep the value defined at the `PortalContainerDefinition` level.
externalSettingsPath	The path of the external properties file to load as default settings to the portal container. This field is optional. If some external settings are defined at the `PortalContainerConfig` level, the two maps of settings will be merged. If a setting with the same name is defined in both maps, it will keep the value defined at the `PortalContainerDefinition` level. The external properties files can be either of type "properties" or of type "xml". The path will be interpreted as follows: The path does not contain any prefix of types: "classpath:", "jar:", "ar:", or "file:". It is assumed that the file could be externalized that can apply the following rules: If a file exists at ${exo-conf-dir}/portal/${portalContainerName}/${externalSettingsPath}, this file will be loaded. If no file exists at the previous path, we then pass the path to the `ConfigurationManager` to be interpreted. If the path contains a prefix, we then assume that the path should be interpreted by the `ConfigurationManager`.

Descriptions of the fields of a PortalContainerDefinition when it is used to define the default portal container:

name (*)	The name of the portal container. This field is optional. The default portal name will be: If this field is not empty, then the default value will be the value of this field. If this field is empty and the value of the parameter default.portal.container is not empty, then the default value will be the value of the parameter. If this field and the parameter default.portal.container are both empty, the default value will be "portal".
restContextName (*)	The name of the context name of the REST web application. This field is optional. The default value will be: If this field is not empty, then the default value will be the value of this field. If this field is empty and the value of the parameter default.rest.context is not empty, then the default value will be the value of the parameter. If this field and the parameter default.rest.context are both empty, the default value will be "rest".
realmName (*)	The name of the realm. This field is optional. The default value will be: If this field is not empty, then the default value will be the value of this field. If this field is empty and the value of the parameter default.realm.name is not empty, then the default value will be the value of the parameter. If both this field and the parameter default.realm.name are empty, the default value will be "exo-domain".
dependencies	All the dependencies of the portal container ordered by loading priority. This field is optional. If the value of this field is not empty, it will be the default list of dependencies.
settings	A `java.util.Map` of internal parameters that we would like to tie the default 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 default portal container. This field is optional. The external properties files can be either of "properties" type or of "xml" type. The path will be interpreted as follows: If the path does not contain any prefix of types: "classpath:", "jar:" or "file:", we assume that the file could be externalized, so we apply the following rules: If a file exists at ${exo-conf-dir}/portal/${externalSettingsPath}, we will load this file. If no file exists at the previous path, we then pass the path to the `ConfigurationManager` to be interpreted. If the path contains a prefix, we then assume that the path can 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 following rules:

If the value of the external setting is null, we ignore the value.
If the value of the external setting is not null and the value of the internal setting is null, the final value will be the external setting value that is of String type.
If 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:
- If the method cannot be found, the final value will be the external setting value that is of String type.
- If the method can be found and the external setting value is an empty String, we ignore the external setting value.
- If the method can be found and the external setting value is not an empty String but the method call fails, we ignore the external setting value.
- If the method can be found and the external setting value is not an empty String and the method call succeeds, the final value will be the external setting value that is of type of the internal setting value.