Version 8

    Extension mechanism in GateIn is good for:

    • dynamically add some configurations specific to your extension
    • redefine some configuration files stored in 02portal.war
    • dynamically add new pages, navigations, porltet preferences and portal config
    • dynamically add new ResourceBundles
    • Overwrite existing RB
    • crete new portal containers
    • dynamically add new HttpFilters, HttpsSessionListeners and ServletContextListeners to the portal
    • dynamically add and/or modify repositories and/or workspaces
    • change look-and-feel etc.

     

    In this how-to-doc we will describe how to create new portal container in GateIn master (3.4) running AS7 or EPP5.

     

    After this how-to doc you will be able to have your site at this URL: http://localhost:8080/myportal.

     

    There are few basic steps:

    1. Create a JAR file with container configuration.xml
    2. Create a WAR with new content
    3. Create a WAR for rest application
    4. Create an EAR file with JAR and 2 WAR modules inside
    5. Create new datasource for new portal container (not necessary when using or GateIn master running AS7)
    6. But don't get scared with these steps, I have created a project to get started on this quickly. Keep reading. ;-)

     

    What you are going to deploy in your /deploy folder is a single EAR file with following structure + datasource definition:

     

    /portal-container.ear                                             
         /lib
              /portal-container-config.jar                         
                   /META-INF
                        MANIFEST.MF
                   /conf
                        configuration.xml
         /portal-container-war.war
              index.jsp
              /WEB-INF
                   web.xml
                   jboss-web.xml
                   /conf
                        configuration.xml
                        /myportal
                             /portal
                                  portal-configuration.xml
                                  /newPortal
                                       portal.xml
                                       pages.xml
                                       navigation.xml
         /portal-container-rest.war
              /META-INF
                   MANIFEST.MF
              /WEB-INF
                   web.xml
                   jboss-web.xml
         /META-INF
              application.xml
              gatein-jboss-beans.xml
              MANIFEST.MF
    

     

    Comments for the structure:

     

    configuration.xml (in portal-container-config.jar) is the entry point for loading the extension  application in portal. Here you specify name for new portal container and the list of  modules.

     

     

         ...snippet of configuration...
         <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
            <component-plugin>
                <name>Add PortalContainer Definitions</name>
                <set-method>registerPlugin</set-method>
                <type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type>
                <init-params>
                    <object-param>
                        <name>myportal</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>gatein-domain-myportal</string></field>                        
                            <field name="externalSettingsPath">
                                <string>configuration.properties</string>
                            </field>
                            <!-- All the dependencies of the portal container ordered by loading priority -->
                            <field name="dependencies">
                                <collection type="java.util.ArrayList">
                                    <value>
                                        <string>eXoResources</string>
                                    </value>
                                    <value>
                                        <string>portal</string>
                                    </value>
                                    <value>
                                        <string>myportal</string>
                                    </value>
                                    ...
                                </collection>
                            </field>
                        </object>
                    </object-param>
                </init-params>
            </component-plugin>
            ...
    

     

    Order  of dependencies is important - it's an order of loading modules in  portal container. In above sample you have entered new name for container, new rest context name and new realm name - we will use this names later.

     

    portal-container-war.war is a web application  that contains files for new portal container. (other configurations are inherited from default portal container)

     

    index.jsp - this is a welcome file for your new portal container which do a redirect from http://localhost:8080/myportal to your default portal (like /myportal/public/newPortal for example)

     

    web.xml (in portal-container-war.war) - must contain a display-name of the extension application (myportal) and complete definition for new portal container - see this file here. There is a big difference in comparison when you are only extending existing portal container.

     

    jboss-web.xml (in portal-container-war.war) - contains your new security domain

     

    <jboss-web>
      <security-domain>java:/jaas/gatein-domain-myportal</security-domain>
    </jboss-web>

     

    configration.xml (in portal-container-war.war) contains imported configuration files. In case of adding  new portal definition, only portal-configuration.xml is imported in  this file. (you are adding only configurations which you want to customize, other configrations are inherited from default portal container)

     

    portal-configuration.xml - in this file you are going to extend only org.exoplatform.portal.config.UserPortalConfigService in which is list of portals set. You add a new portal name in list and you can also set your new portal as a default one.

     

         ...
         <external-component-plugins>
            <target-component>org.exoplatform.portal.config.UserPortalConfigService</target-component>
            <component-plugin>
                <name>new.portal.config.user.listener</name>
                <set-method>initListener</set-method>
                <type>org.exoplatform.portal.config.NewPortalConfigListener</type>
                <description>this listener init the portal configuration</description>
                <init-params>
                    <value-param>
                        <name>default.portal</name>
                        <description>The default portal for checking db is empty or not</description>
                        <value>newPortal</value>
                    </value-param>
                    <object-param>
                        <name>portal.configuration</name>
                        <description>description</description>
                        <object type="org.exoplatform.portal.config.NewPortalConfig">
                            <field name="predefinedOwner">
                                <collection type="java.util.HashSet">
                                    <value>
                                        <string>classic</string>
                                    </value>
                                    <value>
                                        <string>newPortal</string>
                                    </value>
                                </collection>
                            </field>
                            <field name="ownerType">
                                <string>portal</string>
                            </field>
                            <field name="templateLocation">
                                <string>war:/conf/myportal/</string>
                            </field>
                        </object>
                    </object-param>
                </init-params>
            </component-plugin>
        </external-component-plugins>
        ...

     

    Folder /conf/portal/portal/newPortal contains files: portal.xml, navigation.xml, pages.xml in which you can define content of new portal, navigation and pages.

    For more details about portal configuration you can have a look at documentation at: http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/5.1/html/Reference_Guide/chap-Reference_Guide-Portal_Navigation_Configuration.html

     

    portal-container-rest.war - is a new web application for rest services

     

    web.xml (in portal-container-rest.war) - have a display-name 'myrest' and structure is here.

     

    jboss-web.xml (in portal-container-rest.war) - contains your new security domain

     

    <jboss-web>
      <security-domain>java:/jaas/gatein-domain-myportal</security-domain>
    </jboss-web>

     

    portal-container-ear.ear - is an enterprise application which contains config java module and 2 web modules + application.xml with modules definition + gatein-jboss-beans.xml (not with AS7)

     

    gatein-jboss-beans.xml - contains security login modules with new portal container and new security domain. When using GateIn master (3.4) running AS7, security domain names are defined in standalone.xml file instead ($GATEIN_HOME/standalone/configuration/standalone.xml).

     

    <deployment xmlns="urn:jboss:bean-deployer:2.0">

        <application-policy xmlns="urn:jboss:security-beans:1.0" name="gatein-domain-myportal">
            <authentication>
                <login-module code="org.exoplatform.web.security.PortalLoginModule" flag="required">
                    <module-option name="portalContainerName">myportal</module-option>
                    <module-option name="realmName">gatein-domain-myportal</module-option>
                </login-module>
                <login-module
                    code="org.exoplatform.services.security.jaas.SharedStateLoginModule" flag="required">

                    <module-option name="portalContainerName">myportal</module-option>
                    <module-option name="realmName">gatein-domain-myportal</module-option>
                </login-module>
                <login-module
                    code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required">

                    <module-option name="portalContainerName">myportal</module-option>
                    <module-option name="realmName">gatein-domain-myportal</module-option>
                </login-module>
            </authentication>
        </application-policy>

    </deployment>

     

    application.xml - contain definition of bundled modules

     

    <application>
      <display-name>myportal</display-name>
      <description>Portal container extension parent project</description>
      <module>
        <web>
          <web-uri>portal-container-extension-war.war</web-uri>
          <context-root>myportal</context-root>
        </web>
      </module>
      <module>
        <web>
          <web-uri>portal-container-extension-rest.war</web-uri>
          <context-root>myrest</context-root>
        </web>
      </module>
    </application>

     

    MANIFEST.MF - should contain "Dependencies: org.gatein.pc,org.gatein.common,org.hibernate"


    Don't forget to define security domain name in standalone.xml !!! Then just deploy final EAR file to GateIn.

     

    If you are using portal running older version than AS7, before deploying the final EAR at EPP5/GateIn you have to change names in datasources of existing/default container !

    JNDI names must have suffix _portal (it's the name of portal container), e.g. gatein-idm_portal and gatein-jcr_portal.

     

    And you have to create new datasource for new portal container. The file must ends with -ds.xml and it can look like this.

     

     

    More details about extension mechanism in JCR are at: http://docs.jboss.org/exojcr/1.12.6-GA/developer/en-US/html_single/#JCRWithGateIn.HowToExtendMyGateInInstance

    Extensions  are very powerful features which gives you a lot of opportunities to customize portal and have everything on one place under your control.

     

     

    I've also created a mavenized project with new portal container, you can checkout sources from: https://svn.jboss.org/repos/qa/portal/portal-extension/http://anonsvn.jboss.org/repos/qa/portal/portal-container-extension/

    (see the Readme.txt for instructions how to build EAR)

     

    You can also have a look at document how to create new portal at existing portal container