[gatein-commits] gatein SVN: r8220 - epp/docs/branches/5.2/Developer_Guide/en-US.

Author: smumford Date: 2011-12-08 19:50:40 -0500 (Thu, 08 Dec 2011) New Revision: 8220 Modified: epp/docs/branches/5.2/Developer_Guide/en-US/Author_Group.xml epp/docs/branches/5.2/Developer_Guide/en-US/Developer_Guide.xml epp/docs/branches/5.2/Developer_Guide/en-US/Preface.xml epp/docs/branches/5.2/Developer_Guide/en-US/chapter-1-GDG_Introduction.xml epp/docs/branches/5.2/Developer_Guide/en-US/chapter-2-GDG_Architectural_choices.xml epp/docs/branches/5.2/Developer_Guide/en-US/chapter-3-GDG_Design_choices.xml epp/docs/branches/5.2/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml epp/docs/branches/5.2/Developer_Guide/en-US/chapter-5-GDG_Application_development.xml Log: JBEPP-1431: Further QE edits Modified: epp/docs/branches/5.2/Developer_Guide/en-US/Author_Group.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/Author_Group.xml 2011-12-08 22:40:29 UTC (rev 8219) +++ epp/docs/branches/5.2/Developer_Guide/en-US/Author_Group.xml 2011-12-09 00:50:40 UTC (rev 8220) @@ -1,25 +1,59 @@ <?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<authorgroup> - - <author> - <firstname>Vlastimil</firstname> - <surname>Eliáš</surname> - <email&gt;velias(a)redhat.com&lt;/email&gt; - </author> - <author> - <firstname>Thomas</firstname> - <surname>Heute</surname> - <email&gt;theute(a)redhat.com&lt;/email&gt; - </author> - <author> - <firstname>Prabhat</firstname> - <surname>Jha</surname> - <email&gt;prabhat.jha(a)jboss.com&lt;/email&gt; - </author> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> -</authorgroup> + <authorgroup> + <author> + <firstname> + Vlastimil + </firstname> + + <surname> + Eliáš + </surname> + + <email> + velias(a)redhat.com + </email> + </author> + + <author> + <firstname> + Thomas + </firstname> + + <surname> + Heute + </surname> + + <email> + theute(a)redhat.com + </email> + </author> + + <author> + <firstname> + Prabhat + </firstname> + + <surname> + Jha + </surname> + + <email> + prabhat.jha(a)jboss.com + </email> + </author> + + <author> + <firstname> + Scott + </firstname> + + <surname> + Mumford + </surname> + + <email> + smumford(a)redhat.com + </email> + </author> + </authorgroup> Modified: epp/docs/branches/5.2/Developer_Guide/en-US/Developer_Guide.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/Developer_Guide.xml 2011-12-08 22:40:29 UTC (rev 8219) +++ epp/docs/branches/5.2/Developer_Guide/en-US/Developer_Guide.xml 2011-12-09 00:50:40 UTC (rev 8220) @@ -1,13 +1,19 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<book> - <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="chapter-1-GDG_Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="chapter-2-GDG_Architectural_choices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="chapter-3-GDG_Design_choices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="chapter-4-GDG_Portal_Development.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="chapter-5-GDG_Application_development.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</book> + <book> + <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="chapter-1-GDG_Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="chapter-2-GDG_Architectural_choices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="chapter-3-GDG_Design_choices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="chapter-4-GDG_Portal_Development.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="chapter-5-GDG_Application_development.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </book> Modified: epp/docs/branches/5.2/Developer_Guide/en-US/Preface.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/Preface.xml 2011-12-08 22:40:29 UTC (rev 8219) +++ epp/docs/branches/5.2/Developer_Guide/en-US/Preface.xml 2011-12-09 00:50:40 UTC (rev 8220) @@ -1,11 +1,13 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<preface id="pref-Developer_Guide-Preface"> - <title>Preface</title> - <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </xi:fallback> - </xi:include> -</preface> - + <preface id="pref-Developer_Guide-Preface"> + <title>Preface</title> + + <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </xi:fallback> + </xi:include> + </preface> Modified: epp/docs/branches/5.2/Developer_Guide/en-US/chapter-1-GDG_Introduction.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/chapter-1-GDG_Introduction.xml 2011-12-08 22:40:29 UTC (rev 8219) +++ epp/docs/branches/5.2/Developer_Guide/en-US/chapter-1-GDG_Introduction.xml 2011-12-09 00:50:40 UTC (rev 8220) @@ -1,7 +1,9 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="sid-819799"> - - <title>Introduction</title> - <para>This is the EPP Developer Guide. This document is intended for those developing applications and gadgets for the EPP product and outlines options and strategies for successful deployment.</para> - </chapter> + <chapter id="sid-819799"> + <title>Introduction</title> + + <para> + This is the JBoss Enterprise Portal Platform Developer Guide. This document is intended for those developing applications and gadgets for the JBoss Enterprise Portal Platform product and outlines options and strategies for successful deployment. + </para> + </chapter> Modified: epp/docs/branches/5.2/Developer_Guide/en-US/chapter-2-GDG_Architectural_choices.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/chapter-2-GDG_Architectural_choices.xml 2011-12-08 22:40:29 UTC (rev 8219) +++ epp/docs/branches/5.2/Developer_Guide/en-US/chapter-2-GDG_Architectural_choices.xml 2011-12-09 00:50:40 UTC (rev 8220) @@ -1,91 +1,169 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="sid-7372876"> - - <title>Architectural choices</title> - <para>Depending on environment and goals, decisions has to be made regarding the components that will make up the final website. Some elements may already be in place (such as an identity server) and some elements may still be free to choose. This section aims at helping taking the right decisions.</para> - <section id="sid-7372876_GDG-Architecturalchoices-Identityserver"> - - <title>Identity server</title> - <para>EPP 5.2 comes with a component named PicketLink IDM, which is made to adapt to store and retrieve users and groups from various identity servers. We can separate the different options into three:</para> - <orderedlist> - <listitem> - <para> - <emphasis role="strong">Database</emphasis> - : users, groups and their relationships are stored in a RDBMS database. Tables names and column names can be changed, but the overall relationship between tables remains the same. This solution is particularly adapted to a new identity server that will handle thousands of users. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">LDAP</emphasis> - : users, groups and their relationships are stored in an LDAP (or ActiveDirectory) server, the directory structure can be adapted by configuration to the most common scenarios. This solution is particularly adapted to infrastructure that are already using an LDAP server, for infrastructure that will share the server identity among multiple service (and the website being one of them) or for very large set of users (millions). When using LDAP with large number of users, it is recommended to use LDAP tools to do the provisioning of users. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">Custom</emphasis> - : when retrieving users, groups and their relationship cannot be done by configuration, it is possible to implement the Picketlink IDM SPI to implement the methods in charge of retrieving and storing user information. - </para> - </listitem> - </orderedlist> + <chapter id="sid-7372876"> + <title>Architectural choices</title> + <para> - Picketlink IDM also supports mix environments, this is very useful when an LDAP infrastructure is provided but in a read-only mode. Since the website may need to store additional information about users (such as his preferred language or skin), it can combine LDAP + Database, to retrieve users from LDAP but store additional properties in a database. During the calls to the identity API, the information from both sources will be transparently merged. - - For more information about PicketLink IDM, please check the EPP 5.2 reference guide and the PicketLink IDM documentation. + Depending on environment and goals, decisions have to be made regarding the components that will make up the final website. Some elements may already be in place (such as an identity server) and some elements may still be free to choose. This section aims at helping taking the right decisions. </para> - </section> - <section id="sid-7372876_GDG-Architecturalchoices-Storage"> - - <title>Storage</title> - <para> - The portal framework stores page compositions, portlet preferences, gadget code in a database through a Java Content Repository (JCR) API. A set of database servers and JDBC connectors are part of our quality assurance cycles and the certified environments are mentioned - <ulink url="http://www.jboss.com/products/platforms/portals/testedconfigura... - . - </para> - <para>It is important to choose one of the combination or check with a Red Hat contact for specific environments that would differ from this list.</para> - <para>The database schema will be automatically created during the very first startup of the website and then it is required that the database users has sufficient rights to create tables. This privilege can be revoked after the initial startup, also the database content can be exported and imported in a new server. This makes the installation of the product very easy in most cases.</para> - <para>We do not provide additional recommendation to choose a database server over another as long as it is part of our certified environment.</para> - <para>As said earlier content is stored through a JCR API, RDBMS aren't a great fit to store large files and it is possible to configure eXo JCR to store such files in the filesystem instead of database, metadata about the files would still be stored into the database. Note that if the website is running on a cluster the filesystem will need to be accessible from all nodes and a NFS solution needs to be setup. For more details see the notion of "value storage" in the reference guide.</para> - </section> - <section id="sid-7372876_GDG-Architecturalchoices-Cluster"> - - <title>Cluster</title> - <para>Clustering for failover or load-balancing requirements requires to spend more time configuring it for your environment, we made it easy to handle common situations though. There is a cost associated to clustering (EPP 5.2 has some optimization when running on a single node) but the product is designed to linearly scale up so that same performance is added every time a new node is added. All critical parts are kept in sync among nodes and the less critical ones left aside to achieve better performance. It will be equally critical that applications developed for the final websites pay the same attention when it comes to replicate data across a cluster of nodes.</para> - <para>The number of nodes will vary a lot depending on the applications developed and used on the final website. We recommend to do early performance analysis with tools such as JMeter, Grinder etc to measure the impact of heavy loads.</para> - <para>It is usually recommended to run a cluster to achieve high availability.</para> - </section> - <section id="sid-7372876_GDG-Architecturalchoices-SSO"> - - <title>SSO</title> - <para> - If the website is part of a more global infrastructure with various components (the website being one of several), it may be in the benefit of users to put a Single-Sign-On solution in place among them. Various SSO solutions are supported by EPP 5.2 as seen - <ulink url="http://www.jboss.com/products/platforms/portals/testedconfigura... - . In some cases it can be better to have the token manager service on a specific server. - </para> - <para>Summary</para> - <para>By now you should know what infrastructure you will need:</para> - <para>- A database</para> - <para>- Optionally LDAP, depending on your choice</para> - <para>- Optionally NFS, depending on the configuration (mandatory on a cluster with default settings: TODO: More QA on a setup without NFS)</para> - <para>- Optionally an SSO token service</para> - <para>- Optionally, a cluster of nodes</para> - <para>Here is an example of the simplest setup:</para> - <figure> -<title></title> - <mediaobject> - <imageobject> - <imagedata fileref="images/7372876/simpleinfra.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Here is an example of a more complex setup:</para> - <figure> -<title></title> - <mediaobject> - <imageobject> - <imagedata fileref="images/7372876/complexinfra.png"/> - </imageobject> - </mediaobject> - </figure> - </section> - </chapter> + + <section id="sid-7372876_GDG-Architecturalchoices-Identityserver"> + <title>Identity server</title> + + <para> + JBoss Enterprise Portal Platform &VY; comes with a component named PicketLink IDM, which is made to adapt to store and retrieve users and groups from various identity servers. We can separate the different options into three: + </para> + + <orderedlist> + <listitem> + <para> + <emphasis role="strong">Database</emphasis> : users, groups and their relationships are stored in a RDBMS database. Table names and column names can be changed, but the overall relationship between tables remains the same. This solution is particularly adapted to a new identity server that will handle thousands of users. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="strong">LDAP</emphasis> : users, groups and their relationships are stored in an LDAP (or ActiveDirectory) server, the directory structure can be adapted by configuration to the most common scenarios. This solution is particularly suited to infrastructures that already use an LDAP server, infrastructures that will share the server identity among multiple services (and the website being one of them) or for very large sets of users (millions). When using LDAP with large number of users, it is recommended to use LDAP tools to do the provisioning of users. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="strong">Custom</emphasis> : when retrieving users, groups and their relationship cannot be done by configuration, it is possible to use the Picketlink IDM SPI to implement the methods which control retrieving and storing user information. + </para> + </listitem> + </orderedlist> + + <para> + Picketlink IDM also supports mix environments, which is very useful when an LDAP infrastructure is provided in a read-only mode. Since a website may need to store additional information about users (such as their preferred language or skin), it can combine LDAP and database services to retrieve users from LDAP and store additional properties in a database. During the calls to the identity API, the information from both sources will be transparently merged. + </para> + + <para> + For more information about PicketLink IDM, please check the JBoss Enterprise Portal Platform &VY; reference guide and the PicketLink IDM documentation. + </para> + </section> + + <section id="sid-7372876_GDG-Architecturalchoices-Storage"> + <title>Storage</title> + + <para> + The portal framework stores page compositions, portlet preferences, gadget code in a database through a Java Content Repository (JCR) API. A set of database servers and JDBC connectors are part of our quality assurance cycles and the certified environments are mentioned <ulink url="http://www.jboss.com/products/platforms/portals/testedconfigura... . + </para> + + <para> + It is important to choose one of the combinations or check with a Red Hat contact for specific environments that would differ from this list. + </para> + + <para> + The database schema will be automatically created during the very first start up of a website and then it is required that the database users have sufficient rights to create tables. This privilege can be revoked after the initial start up, also the database content can be exported and imported in a new server. This makes the installation of the product very easy in most cases. + </para> + + <para> + We do not provide additional recommendation to choose one database server over another as long as it is one of the certified environment. + </para> + + <para> + As said earlier, content is stored through a JCR API, RDBMS aren't a great fit to store large files and it is possible to configure eXo JCR to store such files in the filesystem instead of a database, whereas metadata about the files would still be stored into the database. Note that if the website is running on a cluster, the filesystem will need to be accessible from all the nodes and a NFS solution needs to be set up. For more details see the notion of "value storage" in the reference guide. + </para> + </section> + + <section id="sid-7372876_GDG-Architecturalchoices-Cluster"> + <title>Cluster</title> + + <para> + Clustering for failover or load-balancing requirements requires spending more time configuring it for your environment, we made it easy to handle common situations though. There is a cost associated with clustering (JBoss Enterprise Portal Platform &VY; has some optimizations when running on a single node), but the product is designed to linearly scale up so that the same performance is added every time a new node is added. All critical parts are kept in sync among nodes and the less critical ones are left aside to achieve better performance. It will be equally critical that applications developed for the final websites pay the same attention when it comes to replicating data across a cluster of nodes. + </para> + + <para> + The number of nodes will vary a lot depending on the applications developed and used on the final website. We recommend to do early performance analysis with tools such as JMeter, Grinder or similar to measure the impact of heavy loads. + </para> + + <para> + It is usually recommended to run a cluster to achieve high availability. + </para> + </section> + + <section id="sid-7372876_GDG-Architecturalchoices-SSO"> + <title>SSO</title> + + <para> + If a website is a part of a more global infrastructure with various components (the website being one of several), it may be in the benefit of users to use a Single-Sign-On solution. Various SSO solutions are supported by JBoss Enterprise Portal Platform &VY; as seen <ulink url="http://www.jboss.com/products/platforms/portals/testedconfigura... . In some cases it can be better to have the token manager service on a specific server. + </para> + + <section id="sid-7372876_GDG-Architecturalchoices-Summary"> + <title>Summary</title> + + <para> + By now you should know what infrastructure you will need: + </para> + + <itemizedlist> + <listitem> + <para> + A database + </para> + </listitem> + + <listitem> + <para> + Optionally LDAP, depending on your choice + </para> + </listitem> + + <listitem> + <para> + Optionally NFS, depending on the configuration (mandatory on a cluster with default settings) + </para> + </listitem> + + <listitem> + <para> + Optionally an SSO token service + </para> + </listitem> + + <listitem> + <para> + Optionally a cluster of nodes + </para> + </listitem> + </itemizedlist> + + <para> + Here is an example of the simplest set-up: + </para> + + <figure> + <title>Example</title> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/7372876/simpleinfra.png" format="PNG" align="center" scale="100"/> + </imageobject> + + <imageobject role="fo"> + <imagedata fileref="images/7372876/simpleinfra.png" format="PNG" align="center" width="150mm"/> + </imageobject> + </mediaobject> + </figure> + + <para> + Here is an example of a more complex set-up: + </para> + + <figure> + <title>Example</title> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/7372876/complexinfra.png" format="PNG" align="center" scale="150"/> + </imageobject> + + <imageobject role="fo"> + <imagedata fileref="images/7372876/complexinfra.png" format="PNG" align="center" width="150mm"/> + </imageobject> + </mediaobject> + </figure> + </section> + </section> + </chapter> Modified: epp/docs/branches/5.2/Developer_Guide/en-US/chapter-3-GDG_Design_choices.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/chapter-3-GDG_Design_choices.xml 2011-12-08 22:40:29 UTC (rev 8219) +++ epp/docs/branches/5.2/Developer_Guide/en-US/chapter-3-GDG_Design_choices.xml 2011-12-09 00:50:40 UTC (rev 8220) @@ -1,122 +1,197 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="sid-7372952"> - - <title>Design choices</title> - <para>Now that the main components of the architecture has been decided, choices must be made on the overall design.</para> - <section id="sid-7372952_GDG-Designchoices-Dashboards"> - - <title>Dashboards</title> - <para>User dashboards may be very costly in a website, as each user will have the opportunity to design his own personal website, it comes with the cost of storing all that information. Efforts have been made (and are still made) to reduce this cost, but there will always be an overhead.</para> - <para>This overhead might be hard to estimate as this will depend a lot on how the users will navigate the website, maybe only a minority will use this functionality, or maybe the website is only made of dashboards. In any case the impact of making this feature available must be measured by:</para> - <itemizedlist> - <listitem> - <para>estimating the number of dashboards and pages that will be created</para> - </listitem> - <listitem> - <para>observing the impact on the database (through JCR) in terms of size</para> - </listitem> - </itemizedlist> - </section> - <section id="sid-7372952_GDG-Designchoices-JCRindexreplicationforclustersetup"> - - <title>JCR index replication for cluster setup</title> + <chapter id="sid-7372952"> + <title>Design choices</title> + <para> - The JCR implementation uses Apache Lucene for indexing the data. The indexes are used to search for content (It can be page nodes or WCM content for instance). - - Lucene isn't cluster-ready but on a cluster, each node will need to be able to search for content and will need to have access to the lucene indexes. - - When is comes to searching, there is always a tradeoff. Everyone would want to achieve all of the following: + Now that the main components of the architecture have been decided, choices must be made on the overall design. </para> - <itemizedlist> - <listitem> - <para>Fast to search</para> - </listitem> - <listitem> - <para>Fast to index</para> - </listitem> - <listitem> - <para>Same search result on each node at the same time</para> - </listitem> - <listitem> - <para>No need to rebuild the index ever (No inconsistency)</para> - </listitem> - <listitem> - <para>No impact on overall performance</para> - </listitem> - <listitem> - <para>Easy to setup (no infrastructure change)</para> - </listitem> - </itemizedlist> - <para>But there are choices to be made. The JCR implementation used by EPP (eXo JCR) makes it possible to configure the storage and retrieval of indexes according to architect's choice on where it is acceptable to lose-up some constraints. For configuration details please refer to the EPP Reference Guide.</para> - <section id="sid-7372952_GDG-Designchoices-Standaloneindex"> - - <title>Standalone index</title> - <para> - This is only for a non-cluster environment, this is obviously the easiest setup, with a combination of in-memory and file based indexes. There is no replication involved so any entry can be found by a search as soon as they are created. - <figure> -<title>TODO Gliffy image title empty</title> -<mediaobject> -<imageobject> - <imagedata fileref="images/7372952/diagram-standalone-index.png"/> - </imageobject> -</mediaobject> -</figure> - </para> - </section> - <section id="sid-7372952_GDG-Designchoices-Localindex"> - - <title>Local index</title> - <para> - This environment is easy to setup, each node keeps a local copy of the full indexes so that when a search is requested on a node, there is no network communication requested. The downside is that when a node indexes an item, it requires to replicate that index on each and every node. If a node is unavailable at that time, it may miss an index update request and then the different nodes may be inconsistent. + + <section id="sid-7372952_GDG-Designchoices-Dashboards"> + <title>Dashboards</title> - Also when a node is added it has to recreate it's own full index. + <para> + User dashboards may be very costly in a website. Each user has an opportunity to design his own personal website, it comes with the cost of storing all that information. Efforts have been made (and are still being made) to reduce this cost, but there will always be an overhead. + </para> - An alternative to this setup is to ask a node to retrieve the info from a coordinator on each search, it makes the startup of the new node faster but impacts its performance during the runtime. This setup is new to EPP 5.2. - </para> - <para> - <figure> -<title>TODO InformalFigure image title empty</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/7372952/diagram-local-index.png"/> - </imageobject> - </mediaobject> - </figure> - </para> + <para> + This overhead might be hard to estimate as this will depend a lot on how the users will navigate through the website. Maybe only a minority will use this functionality, or maybe the website is only made of dashboards. In any case the impact of making this feature available must be measured by: + </para> + + <itemizedlist> + <listitem> + <para> + estimating the number of dashboards and pages that will be created + </para> + </listitem> + + <listitem> + <para> + observing the impact on the database (through JCR) in terms of size + </para> + </listitem> + </itemizedlist> </section> - <section id="sid-7372952_GDG-Designchoices-Sharedindex"> - - <title>Shared index</title> - <para> - In this setup there is a unique index created and shared among all nodes. It requires to configure the infrastructure so that a network file system is installed where all nodes can read content. + + <section id="sid-7372952_GDG-Designchoices-JCRindexreplicationforclusterset-up"> + <title>JCR index replication for cluster set-up</title> - Advantages: - </para> - <itemizedlist> - <listitem> - <para>Consistency, all the nodes see the same data</para> - </listitem> - </itemizedlist> - <para>Drawback:</para> - <itemizedlist> - <listitem> - <para>Requires a highly available NFS setup (NFS 4 is recommended)</para> - </listitem> - <listitem> - <para>More network communication</para> - </listitem> - </itemizedlist> - <para> - <figure> -<title>TODO InformalFigure image title empty</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/7372952/diagram-shared-index.png"/> - </imageobject> - </mediaobject> - </figure> - </para> + <para> + The JCR implementation uses Apache Lucene for indexing the data. The indexes are used to search for content (It can be page nodes or WCM content for instance). + </para> + + <para> + Lucene isn't cluster-ready, but on a cluster, each node will need to be able to search for content and will need to have access to the lucene indexes. + </para> + + <para> + When is comes to searching, there is always a tradeoff. Everyone would want to achieve all of the following: + </para> + + <itemizedlist> + <listitem> + <para> + Fast to search + </para> + </listitem> + + <listitem> + <para> + Fast to index + </para> + </listitem> + + <listitem> + <para> + Same search result on each node at the same time + </para> + </listitem> + + <listitem> + <para> + No need to rebuild the index ever (No inconsistency) + </para> + </listitem> + + <listitem> + <para> + No impact on overall performance + </para> + </listitem> + + <listitem> + <para> + Easy to set-up (no infrastructure change) + </para> + </listitem> + </itemizedlist> + + <para> + But there are choices to be made. The JCR implementation used by JBoss Enterprise Portal Platform (eXo JCR) makes it possible to configure the storage and retrieval of indexes according to architect's choice on where it is acceptable to relax some constraints. For configuration details please refer to the JBoss Enterprise Portal Platform Reference Guide. + </para> + + <section id="sid-7372952_GDG-Designchoices-Standaloneindex"> + <title>Standalone index</title> + + <para> + This is only for a non-cluster environment, this is obviously the easiest set-up, with a combination of in-memory and file based indexes. There is no replication involved so any entry can be found by a search as soon as it is created. + </para> + + <figure> + <title>Example</title> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/7372952/diagram-standalone-index.png" format="PNG" align="center" scale="100"/> + </imageobject> + + <imageobject role="fo"> + <imagedata fileref="images/7372952/diagram-standalone-index.png" format="PNG" align="center" width="150mm"/> + </imageobject> + </mediaobject> + </figure> + </section> + + <section id="sid-7372952_GDG-Designchoices-Localindex"> + <title>Local index</title> + + <para> + This environment is easy to set up, each node keeps a local copy of the full indexes so that when a search is requested on a node, there is no network communication required. The downside is that when a node indexes an item, it is required to replicate that index on each and every node. If a node is unavailable at that time, it may miss an index update request and then the different nodes may be inconsistent. + </para> + + <para> + Also when a node is added, it has to recreate it's own full index. + </para> + + <para> + An alternative to this set-up is to ask a node to retrieve the info from a coordinator on each search, which makes the startup of the new node faster, but impacts its performance during the runtime. This set-up is new to JBoss Enterprise Portal Platform &VY;. + </para> + + <figure> + <title>Example</title> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/7372952/diagram-local-index.png" format="PNG" align="center" scale="100"/> + </imageobject> + + <imageobject role="fo"> + <imagedata fileref="images/7372952/diagram-local-index.png" format="PNG" align="center" width="150mm"/> + </imageobject> + </mediaobject> + </figure> + </section> + + <section id="sid-7372952_GDG-Designchoices-Sharedindex"> + <title>Shared index</title> + + <para> + In this set-up there is a unique index created and shared among all the nodes. It is required to configure the infrastructure so that a network file system is installed where all nodes can read content. + </para> + + <para> + Advantages: + </para> + + <itemizedlist> + <listitem> + <para> + Consistency, all the nodes see the same data + </para> + </listitem> + </itemizedlist> + + <para> + Drawback: + </para> + + <itemizedlist> + <listitem> + <para> + Requires a highly available NFS set-up (NFS 4 is recommended) + </para> + </listitem> + + <listitem> + <para> + More network communication + </para> + </listitem> + </itemizedlist> + + <figure> + <title>Example</title> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/7372952/diagram-shared-index.png" format="PNG" align="center" scale="100"/> + </imageobject> + + <imageobject role="fo"> + <imagedata fileref="images/7372952/diagram-shared-index.png" format="PNG" align="center" width="150mm"/> + </imageobject> + </mediaobject> + </figure> + </section> </section> - </section> - </chapter> + </chapter> Modified: epp/docs/branches/5.2/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml 2011-12-08 22:40:29 UTC (rev 8219) +++ epp/docs/branches/5.2/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml 2011-12-09 00:50:40 UTC (rev 8220) @@ -1,79 +1,124 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="sid-8094155"> - - <title>Portal Development</title> - <section id="sid-7372962"> - - <title>Portal containers</title> - <para>In a single instance (or cluster) of EPP, multiple portals can be running and share resources with other portals with two level of granularities:</para> - <itemizedlist> - <listitem> - <para>Portal Containers: A portal container can host multiple sites, and an EPP instance can host multiple portal containers</para> - </listitem> - <listitem> - <para>Site: A site can have a unique identity, with its own skin applied, set of pages...</para> - </listitem> - </itemizedlist> - <para> - The biggest granularity is what is called "Portal Containers", a Portal Container can host multiple "Sites". Those two components have a unique identifier that can be found in the default URL Mapping according to the following scheme: - <ulink url="http://localhost:8080/"/> - &lt;portalcontainer&gt;/&lt;site&gt; - </para> - <para> - When creating a website, it is possible to create a portal container from scratch or extend an existing one. It is then possible to extend the portal container which is accessed at - <ulink url="http://localhost:8080/portal"/> - on the out of the box solution, this is the recommended way. While running multiple portal containers is possible, it's usually better to keep those on separate installation, note that multiple websites can run in a single portal container and share some services. - </para> - <para> - By providing an extension you can benefit from the portal provided by EPP and be able to customize the parts you want. The benefits over directly modifying the shipped files is that it will make the updates much easier (By just replacing the archives provided by EPP). - <figure> -<title>TODO Gliffy image title empty</title> -<mediaobject> -<imageobject> - <imagedata fileref="images/7372962/portalextensionstructure.png"/> - </imageobject> -</mediaobject> -</figure> - </para> - <section id="sid-7372962_GDG-Portalcontainers-Portalextension"> - - <title>Portal extension</title> - <para>A portal extension is packaged as an Enterprise ARchive (EAR), a configuration file allows to define which services are required and by ordering those, it is possible to modify some elements. It can be a configuration setting, a translation, a visual template, a page to add...</para> - <para> - Portal extensions can shadow existing services, a portal will usually be composed of various extensions, each of them usually add services. - <figure> -<title>TODO Gliffy image title empty</title> -<mediaobject> -<imageobject> - <imagedata fileref="images/7372962/portalExtensions.png"/> - </imageobject> -</mediaobject> -</figure> - In a portal extension, elements are shadowed by using the same directory location, so if one wants to rewrite the groovy template of the HomePagePortlet which is located in: gatein.ear/02portal.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl it would be located in an extension such as myExtension/myWar.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl. The ordering will be defined by the portal extension configuration. - </para> + <chapter id="sid-8094155"> + <title>Portal Development</title> + + <section id="sid-7372962"> + <title>Portal containers</title> + + <para> + In a single instance (or cluster) of JBoss Enterprise Portal Platform, multiple portals can be running and share resources with other portals with two level of granularity: + </para> + + <itemizedlist> + <listitem> + <para> + Portal Containers: A portal container can host multiple sites, and an JBoss Enterprise Portal Platform instance can host multiple portal containers + </para> + </listitem> + + <listitem> + <para> + Site: A site can have a unique identity, with its own skin applied to a set of pages. + </para> + </listitem> + </itemizedlist> + + <para> + The biggest granularity is what is called "Portal Containers". A Portal Container can host multiple "Sites". Those two components have a unique identifier that can be found in the default URL mapping according to the following scheme: <code> <ulink url="http://localhost:8080/"/> &lt;portalcontainer&gt;/&lt;site&gt; </code> + </para> + + <para> + When creating a website, it is possible to create a portal container from scratch or extend an existing one. It is then possible to extend the portal container which is accessed at <ulink url="http://localhost:8080/portal"/> on the out of the box solution, this is the recommended way. While running multiple portal containers is possible, it's usually better to keep those on separate installation. Note that multiple websites can run in a single portal container and share some services. + </para> + + <para> + By providing an extension you can benefit from the portal provided by JBoss Enterprise Portal Platform and be able to customize the parts you want. The benefit over directly modifying the shipped files is that it will make the updates much easier (by just replacing the archives provided by JBoss Enterprise Portal Platform). + <figure> + <title>Example</title> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/7372962/portalextensionstructure.png" format="PNG" align="center" scale="100"/> + </imageobject> + + <imageobject role="fo"> + <imagedata fileref="images/7372962/portalextensionstructure.png" format="PNG" align="center" width="150mm"/> + </imageobject> + </mediaobject> + </figure> + </para> + + <section id="sid-7372962_GDG-Portalcontainers-Portalextension"> + <title>Portal extension</title> + + <para> + A portal extension is packaged as an Enterprise ARchive (EAR), a configuration file allows to define which services are required and by ordering those, it is possible to modify some elements. It can be a configuration setting, a translation, a visual template, a page to add. + </para> + + <para> + Portal extensions can shadow existing services, a portal will usually be composed of various extensions, which usually add services. + </para> + + <figure> + <title>Example</title> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/7372962/portalExtensions.png" format="PNG" align="center" scale="10"/> + </imageobject> + + <imageobject role="fo"> + <imagedata fileref="images/7372962/portalExtensions.png" format="PNG" align="center" width="150mm"/> + </imageobject> + </mediaobject> + </figure> + + <para> + In a portal extension, elements are shadowed by using the same directory location, so if you want to rewrite the groovy template of the HomePagePortlet which is located in <filename>gatein.ear/02portal.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl</filename>, it would be in an extension at a location such as <filename>myExtension/myWar.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl</filename>. The ordering will be defined by the portal extension configuration. + </para> + </section> </section> - </section> - <section id="sid-8094158"> - - <title>Visual identity</title> - <para>A portal visual identity will be made of the HTML produced by the result of the portal aggregation (the components that makes a page like columns, rows combined with the content produced by the portlets) and associated CSS files.</para> - <para>EPP allows to deploy multiple skins which consists of CSS files, it makes it possible to apply styling on the page compositions and components of a page (Portlets). Different skins can be applied to the different websites, also if made available to the users, they can choose their preferred skin.</para> - <section id="sid-8094158_GDG-Visualidentity-Customizingtheloginpage"> - - <title>Customizing the login page</title> - <para>When accessing a page that requires privileges, a login page is showing up, that page can be customized by using an extension. To do so it would be enough to copy the file located at:</para> - <example> - <title>Login JSP</title> - <programlisting>gatein.ear/02portal.war/login/jsp/login.jsp</programlisting> - </example> - <para>and include it in the portal extension such as myExtension.ear/myWar.war/login/jsp/login.jsp</para> - <para>All the logic must be carefully kept in the login page so that the portal will keep working as it should.</para> - <para>To modify the modal window which pops up when the user decides to sign-in, the extension would have a modified copy of:</para> - <example> - <title>Login Form</title> - <programlisting>gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</programlisting> - </example> + + <section id="sid-8094158"> + <title>Visual identity</title> + + <para> + A portal visual identity is made of HTML produced as a result of portal aggregation (the components that make a page like columns and rows combined with the content produced by the portlets) and associated CSS files. + </para> + + <para> + JBoss Enterprise Portal Platform allows to deploy multiple skins consisting of CSS files, which makes it possible to apply styling to the page compositions and components of a page (portlets). Different skins can be applied to the different websites, also if made available to the users, they can choose their preferred skin. + </para> + + <section id="sid-8094158_GDG-Visualidentity-Customizingtheloginpage"> + <title>Customizing the login page</title> + + <para> + When accessing a page that requires privileges, a login page is shown and it can be customized by using an extension. To do so, it would be enough to copy the file located at: + </para> + + <example> + <title>Login JSP</title> +<programlisting>gatein.ear/02portal.war/login/jsp/login.jsp</programlisting> + </example> + + <para> + and include it in a portal extension such as myExtension.ear/myWar.war/login/jsp/login.jsp + </para> + + <para> + All the logic must be carefully kept in the login page so that the portal will keep working as it should. + </para> + + <para> + To modify the modal window which pops up when the user decides to sign-in, the extension would have a modified copy of: + </para> + + <example> + <title>Login Form</title> +<programlisting>gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</programlisting> + </example> + </section> </section> - </section> - </chapter> + </chapter> Modified: epp/docs/branches/5.2/Developer_Guide/en-US/chapter-5-GDG_Application_development.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/chapter-5-GDG_Application_development.xml 2011-12-08 22:40:29 UTC (rev 8219) +++ epp/docs/branches/5.2/Developer_Guide/en-US/chapter-5-GDG_Application_development.xml 2011-12-09 00:50:40 UTC (rev 8220) @@ -1,33 +1,49 @@ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="sid-819803"> - - <title>Application development</title> - <section id="sid-819807"> - - <title>Gadget Development</title> - <section id="sid-819807_GDG-GadgetDevelopment-Introduction"> - - <title>Introduction</title> - <para>In the context of EPP, gadgets are those as defined by the Google OpenSocial specifications. Since EPP 5.2, the portal framework includes Apache Shindig 2.0 which is made to support the version 0.9 and 1.0 of OpenSocial.</para> - <para>Within a portal it is possible to embed any OpenSocial gadget on a page or within the user dashboards, gadgets can be added to the application registry, or links can be added within the mini-composer (see the User Guide).</para> + <chapter id="sid-819803"> + <title>Application development</title> + + <section id="sid-819807"> + <title>Gadget Development</title> + + <section id="sid-819807_GDG-GadgetDevelopment-Introduction"> + <title>Introduction</title> + + <para> + In the context of JBoss Enterprise Portal Platform, gadgets are defined by the Google OpenSocial specifications. Since JBoss Enterprise Portal Platform &VY;, the portal framework includes Apache Shindig 2.0 which is made to support the version 0.9 and 1.0 of OpenSocial. + </para> + + <para> + Within a portal, it is possible to embed any OpenSocial gadget in a page or in a user's dashboard. Gadgets can be added to the application registry and links can be added to the mini-composer (see the JBoss Enterprise Portal Platform User Guide). + </para> + </section> + + <section id="sid-819807_GDG-GadgetDevelopment-DevelopingGadgets"> + <title>Developing Gadgets</title> + + <para> + OpenSocial gadgets are made of standard HTML and javascript. The container offers an API, the documentation for which is available <ulink url="http://opensocial-resources.googlecode.com/svn/spec/1.0/Core-Ga... . + </para> + + <para> + Note that, unlike portlets, a gadget has very little knowledge of its context (the portal) and its integration within the portal may be more limited (in terms of visual integration for instance). + </para> + + <para> + While Google Web Toolkit (GWT) applications can also technically be used as gadgets and GWT makes it easy to write user-friendly applications, we do not recommend its usage as its support can be limited and Google's strategy to keep GWT applications running as gadgets cannot clearly be established. Consequently, GWT applications are not supported by the JBoss Enterprise Portal Platform support agreement. + </para> + </section> </section> - <section id="sid-819807_GDG-GadgetDevelopment-DevelopingGadgets"> - - <title>Developing Gadgets</title> - <para> - OpenSocial gadgets are made of standard HTML and javascript. The container offers an API for which the documentation is available - <ulink url="http://opensocial-resources.googlecode.com/svn/spec/1.0/Core-Ga... - . - </para> - <para>Note that unlike portlets, a gadget has very little knowledge of its context (the portal) and its integration within the portal may be more limited (in terms of visual integration for instance).</para> - <para>While Google Web Toolkit (GWT) applications can also technically be used as gadgets and makes it easy to write user-friendly applications, we do not recommend its usage as its support can be limited and Google's strategy to keep GWT applications running as gadgets cannot clearly be established. Consequently GWT applications are not supported by the EPP support agreement.</para> + + <section id="sid-819805"> + <title>Portlet Development</title> + + <para> + JBoss Enterprise Portal interface is fully customized with applications called portlets. Application development can be done by using the plain Portlet specification JSR-286 (refer to the "Portlet Primer" chapter in the JBoss Enterprise Portal Platform Reference Guide for more information), but it is also possible to use the JBoss Portlet Bridge to write applications with JSF and/or RichFaces and/or Seam, (refer to the "Getting started with JBoss Portlet Bridge" chapter of the JBoss Enterprise Portal Platform Reference Guide). + </para> + + <para> + Depending on the complexity of the application and the familiarity of the team with JSF, one approach or the other can be the right choice for your team. + </para> </section> - </section> - <section id="sid-819805"> - - <title>Portlet Development</title> - <para>JBoss Enterprise Portal interface is fully customized with applications called portlets. Application development can be done by using the plain Portlet specification (JSR-286) (See the "Portlet Primer" chapter in the reference guide) but it is also possible to use the JBoss Portlet Bridge to write applications with JSF and/or RichFaces and/or Seam, see the "Getting started with JBoss Portlet Bridge" chapter of the reference guide.</para> - <para>Depending on the complexity of the application and the familiarity of the team with JSF, one approach or the other can be the right choice for your team.</para> - </section> - </chapter> + </chapter>