Version 10

    Author : Michal Vanco

     

    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
    • create 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 an OOB Gatein, you currently get portal such as http://host:8080/portal/public/classic . This allows you to get http://host:8080/portal/public/newportal

     

    In this how-to-doc we will describe how to create new portal in existing portal container. There are few basic steps:

    1. Create a JAR file with configuration.xml
    2. Create a WAR with new/extended content
    3. Create an EAR file with JAR and WAR modules inside
    4. Rename default datasources
    5. 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:

    /NewPortal.ear                                            

         /NewPortalConfig.jar                        

              /META-INF

                   MANIFEST.MF

              /conf

                   configuration.xml

         /NewPortal.war

              /WEB-INF

                   web.xml

                   /conf

                        configuration.xml

                        /portal

                             /portal

                                  portal-configuration.xml

                                  /newPortal

                                       portal.xml

                                       pages.xml

                                       navigation.xml

         /META-INF

              application.xml
              MANIFEST.MF

    Comments for the structure:

    configuration.xml (in NewPortalConfig.jar) is the entry point for loading the extension application in portal. In this file you define which portal container definition you are overriding and you are specifying 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>portal</name>
                        <object type="org.exoplatform.container.definition.PortalContainerDefinition">
                            <!-- The name of the portal container -->
                            <field name="name"><string>portal</string></field>
                            <!-- The name of the context name of the rest web application -->
                            <field name="restContextName"><string>rest</string></field>
                            <!-- The name of the realm -->
                            <field name="realmName"><string>gatein-domain</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>portal-ext</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. For example in our case the 'portal-ext' must be in list after the 'portal' because it's overriding files in default portal container.

     

    NewPortal.war is a web application that extends files of portal container which is being extended. (of course it can contain new files like portlets or new configuration files)

     

    web.xml must contain a display-name of the extension application (portal-ext) and also the listener org.exoplatform.container.web.PortalContainerConfigOwner

     

    configuration.xml (in NewPortal.war) contains imported configuration files. In case of adding new portal definition, only portal-configuration.xml is imported in this file

     

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

     

    As you can see the NewPortal.ear is a parent folder with config .jar and webapp content. There is also application.xml file with links to jar and war modules.

        ...
        <display-name>NewPortalEar</display-name>
        <module>
            <web>
                <web-uri>NewPortal.war</web-uri>
                <context-root>portal-ext</context-root>
            </web>
        </module>
        <module>
            <java>NewPortalConfig.jar</java>
        </module>
        ...

     

    !!!Before deploying the final EAR at EPP5/GateIn you have to change names in datasources!!!

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

     

     

    And 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 portal extension, you can checkout sources from: http://anonsvn.jboss.org/repos/qa/portal/portal-extension (see the Readme.txt for instructions how to build EAR)