The previous releases of JBoss Portal did not have an external schema to validate the various XML descriptors although it was internally validated by the portal. Since 2.6 we have worked on providing Document Type Definition (DTD) for the various descriptors. The DTD validation will be only effective if you XML descriptors declares it like that:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD Portal Object 2.6//EN" "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> ...
If you do not perform the declaration then the previous mechanism will be used. The main difference between using the DTD and not is that the additional DTD validation is more strict specifically on the order of the XML elements. The following example will be accepted without the DTD declaration and will not with the DTD declaration:
<?xml version="1.0" encoding="UTF-8"?> <deployment> <if-exists>overwrite</if-exists> <parent-ref>default.default</parent-ref> ... </deployment>
The correct descriptor is rather:
<?xml version="1.0" encoding="UTF-8"?> <deployment> <parent-ref>default.default</parent-ref> <if-exists>overwrite</if-exists> ... </deployment>
The various DTD available are:
- For -object.xml descriptors: "-//JBoss Portal//DTD Portal Object 2.6//EN"
- For jboss-app.xml descriptors: "-//JBoss Portal//DTD JBoss Web Application 2.6//EN"
- For jboss-portlet.xml descriptors: "-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
- For portlet-instances.xml descriptors: "-//JBoss Portal//DTD Portlet Instances 2.6//EN"
Those files are available in the jboss-portal.sar/dtd/ folder
Element <!ELEMENT portlet-app (remotable?,portlet*,service*)>
The remotable element is used to configure the default behavior of the portlets with respect to WSRP exposure. For each portlet defined in portlet.xml, it is possible to configure specific settings of the portlet container. It is also possible to inject services in the portlet context of the application using the service elements.
Element <!ELEMENT portlet (portlet-name,remotable?,ajax?,session-config?,transaction?,header-content?)>
Additional configuration for a portlet. The portlet-name defines the name of the portlet. It must match a portlet defined already in portlet.xml of the same web application. The remotable element configures the portlet exposure to WSRP. If no value is present then the value considered is either the value defined globally at the portlet application level or false. The trans-attribute value specifies the behavior of the portlet when it is invoked at runtime with respect to the transactionnal context. According to how the portlet is invoked a transaction may exist or not before the portlet is invoked. Usually in the local context the portal transaction could be present. By default the value considered is NotSupported which means that the portal transaction will be suspended for the duration of the portlet invocation. Example: <portlet> <portlet-name>MyPortlet</portlet-name> <remotable>true</remotable> <trans-attribute>Required</trans-attribute> </portlet>
Element <!ELEMENT portlet-name (#PCDATA)>
The portlet name.
Element <!ELEMENT remotable (#PCDATA)>
The remotable value is used for WSRP exposure. The accepted values are the litterals true of false.
Element <!ELEMENT ajax (partial-refresh)>
The ajax tag allows to configure the ajax capabilities of the portlet. If the portlet is tagged as partial-refresh then the portal may use partial page refreshing and render only that portlet. If the portlet partial-refresh value is false, then the portal will perform a full page refresh when the portlet is refreshed.
Element <!ELEMENT partial-refresh (#PCDATA)>
The authorized values for the partial-refresh element are true or false.
Element <!ELEMENT session-config (distributed)>
This element configure the portlet session of the portlet. The distributed element instructs the container to distribute the session attributes using the portal session replication. It applies only to local portlets are not to remote portlets. The default value is false. Example: <session-config> <distributed>true</distributed> </session-config>
Element <!ELEMENT distributed (#PCDATA)>
The authorized values for the distributed element are true or false.
Element <!ELEMENT transaction (trans-attribute)>
Defines how the portlet behaves with the transactionnal context. The default value is Never. Example: <transaction> <trans-attribute>Required</transaction> <transaction>
Element <!ELEMENT trans-attribute (#PCDATA)>
The trans-attribute value defines the transactionnal behavior. The accepted values are Required, Mandatory, Never, Supports, NotSupported and RequiresNew.
Element <!ELEMENT header-content (link | script | meta)*>
Specify content which should be included in the portal aggregated page when the portlet is present on that page. This setting only applies when the portlet is used in the local mode.
Element <!ELEMENT link EMPTY>
No content is allowed inside an link element.
Element <!ELEMENT script (#PCDATA)>
The script header element can contain inline script definitions.
Element <!ELEMENT meta EMPTY>
No content is allowed for meta element.
Element <!ELEMENT service (service-name,service-class,service-ref)>
Declare a service that will be injected by the portlet container as an attribute of the portlet context. Example: <service> <service-name>UserModule</service-name> <service-class>org.jboss.portal.identity.UserModule</service-class> <service-ref>:service=Module,type=User</service-ref> </service> In the portlet it is then possible to use it by doing a lookup on the service name, for example in the init() lifecycle method : public void init() { UserModule userModule = (UserModule)getPortletContext().getAttribute("UserModule"); }Element <!ELEMENT service-name (#PCDATA)>
The service name that will be used to bind the service as a portlet context attribute.
Element <!ELEMENT service-class (#PCDATA)>
The full qualified name of the interface that the service implements.
Element <!ELEMENT service-ref (#PCDATA)>
The reference to the service. In the JMX Microkernel environment it consist of the JMX name of the service MBean. For an MBean reference if the domain is left out, then the current domain of the portal will be used.
Element <!ELEMENT deployments (deployment*)>
The deployements element is a container for deployment elements.
Element <!ELEMENT deployment (if-exists?,instance)>
The deployment is a container for an instance element.
Element <!ELEMENT if-exists (#PCDATA)>
The if-exists element is used to define action to take if instance with such name is already present. Possible values are overwrite or keep . Overwrite will destroy the existing object in the database and create a new one, based on the content of the deployment. Keep will maintain the existing object deployment or create a new one if it does not yet exist.
Element <!ELEMENT instance (instance-id,portlet-ref,preferences?,security-constraint?)>
The instance element is used to create an instance of a portlet from the portlet application of the same war file containing the portlet-instances.xml file. The portlet will be created and configured only if the portlet is present and an instance with such a name does not already exist. Example : <instance> <instance-id>MyPortletInstance</instance-id> <portlet-ref>MyPortlet</portlet-ref> <preferences> <preference> <name>abc</name> <value>def</value> </preference> </preferences> <security-constraint> <policy-permission> <role-name>User</role-name> <action-name>view</action-name> </policy-permission> </security-constraint> </instance>Element <!ELEMENT instance-id (#PCDATA)>
The identifier of the instance.
Element <!ELEMENT portlet-ref (#PCDATA)>
The reference to the portlet which is its portlet name.
Element <!ELEMENT preferences (preference)>
The preferences element configures the instance with a specific set of preferences.
Element <!ELEMENT preference (name,value)>
The preference configure one preference of a set of preferences.
Element <!ELEMENT name (#PCDATA)>
A name.
Element <!ELEMENT value (#PCDATA)>
A string value.
Element <!ELEMENT security-constraint (policy-permission*)>
The security-constraint element is a container for policy-permission elements Examples: <security-constraint> <policy-permission> <role-name>User</role-name> <action-name>view</action-name> </policy-permission> </security-constraint> <security-constraint> <policy-permission> <unchecked/> <action-name>view</action-name> </policy-permission> </security-constraint>Element <!ELEMENT policy-permission (action-name*,unchecked?,role-name*)>
The policy-permission element is used to secure a specific portlet instance based on a user's role.
Element <!ELEMENT action-name (#PCDATA)>
The action-name element is used to define the access rights given to the role defined. Possible values are: * view - Users can view the page. * viewrecursive - Users can view the page and child pages. * personalize - Users are able to view AND personalize the page. * personalizerecursive - Users are able to view AND personalize the page AND its child pages.Element <!ELEMENT unchecked EMPTY>
The unchecked element is used to define (if present) that anyone can view this instance
Element <!ELEMENT role-name (#PCDATA)>
The role-name element is used to define a role that this security constraint will apply to * <role-name>SOMEROLE</role-name> Access to this instance is limited to the defined role.
Element <!ELEMENT deployments (deployment*)>
The deployements element is a generic container for deployment elements.
Element <!ELEMENT deployment (parent-ref,if-exists?,(context | portal | page | window))>
The deployment is a generic container for portal object elements. The parent-ref child gives the name of the parent object that the current object will use as parent. The optional if-exists element define the behavior when a portal object which an identical name is already child of the parent element. The default behavior of the if-exist tag is to keep the existing object and not create a new object. The last element is the portal object itself. Example: <deployment> <parent-ref>default</parent-ref> <page> ... </page> </deployment> All portal objects have a common configuration which can be : 1/ a listener : specifies the id of a listener is the listener registry. A listener object is able to listen portal events which apply to the portal node hierarchy. 2/ properties : a set of generic properties owned by the portal object. Some properties can drive the behavior of the object. 3/ security-constraint : defines security configuration of the portal object.Element <!ELEMENT parent-ref (#PCDATA)>
Contains a reference to the parent object. The naming convention for naming object is to concatenate the names of the path to the object and separate the names by a dot. If the path is empty then the empty string must be used. Example: <parent-ref/> the root having an empty path <parent-ref>default</parent-ref> the object with the name default under the root having the path (default) <parent-ref>default.default</parent-ref> the object with the path (default,default)
Element <!ELEMENT if-exists (#PCDATA)>
The authorized values are overwrite and keep. Overwrite means that the existing object will be destroyed and the current declaration will be used. Keep means that the existing object will not be destroyed and no creation hence will be done.
Element <!ELEMENT context (context-name,properties?,listener?,security-constraint?,portal*)>
A portal object of type context. A context type represent a node in the tree which does not have a visual representation. It can exist only under the root. A context can only have children with the portal type.
Element <!ELEMENT context-name (#PCDATA)>
The context name value.
Element <!ELEMENT portal (portal-name,supported-modes,supported-window-states?,properties?,listener?,security-constraint?,page*)>
A portal object of type portal. A portal type represents a virtual portal and can have children of type page. In addition of the common portal object elements it support also the declaration of the modes and the window states it supports. If no declaration of modes or window states is done then the default value will be respectively (view,edit,help) and (normal,minimized,maximized).
Element <!ELEMENT portal-name (#PCDATA)>
The portal name value.
Element <!ELEMENT supported-modes (mode*)>
The supported modes of a portal. Example: <supported-mode> <mode>view</mode> <mode>edit</mode> <mode>help</mode> </supported-mode>
Element <!ELEMENT mode (#PCDATA)>
A portlet mode value.
Element <!ELEMENT supported-window-states (window-state*)>
The supported window states of a portal. Example: <supported-window-states> <window-state>normal</window-state> <window-state>minimized</window-state> <window-state>maximized</window-state> </supported-window-states>
Element <!ELEMENT window-state (#PCDATA)>
A window state value.
Element <!ELEMENT page (page-name,properties?,listener?,security-constraint?,(page | window)*)>
A portal object of type page. A page type represents a page which can have children of type page and window. The children windows are the windows of the page and the children pages are the subpages of this page.
Element <!ELEMENT page-name (#PCDATA)>
The page name value.
Element <!ELEMENT window (window-name,(instance-ref | content),region,height,properties?,listener?)>
A portal object of type window. A window type represents a window. Beside the common properties a window has a content and belong to a region on the page. The instance-ref or content tags are used to define the content of the window. The usage of the content tag is generic and can be used to describe any kind of content. The instance-ref is a shortcut to define a content type of portlet which points to a portlet instance. The region and height defines how the window is placed in the page.
Element <!ELEMENT window-name (#PCDATA)>
The window name value.
Element <!ELEMENT instance-ref (#PCDATA)>
Define the content of the window as a reference to a portlet instance. The value is the id of the instance. Example: <instance-ref>MyPortletInstance</instance-ref>
Element <!ELEMENT content (content-type,content-uri)>
Define the content of the window in a generic manner. The content is define by the type of the content and an URI which acts as an identificator for the content. Example: <content> <content-type>portlet</content-type> <content-uri>MyPortletInstance</content-uri> </content> <content> <content-type>cms</content-type> <content-uri>/default/index.html</content-uri> </content>
Element <!ELEMENT content-type (#PCDATA)>
The content type of the window.
Element <!ELEMENT content-uri (#PCDATA)>
The content URI of the window.
Element <!ELEMENT region (#PCDATA)>
The region the window belongs to.
Element <!ELEMENT height (#PCDATA)>
The height of the window in the particular region.
Element <!ELEMENT listener (#PCDATA)>
Define a listener for a portal object. The value is the id of the listener.
Element <!ELEMENT properties (property*)>
A set of generic properties for the portal object.
Element <!ELEMENT property (name,value)>
A generic string property.
Element <!ELEMENT name (#PCDATA)>
A name value.
Element <!ELEMENT value (#PCDATA)>
A value.
Element <!ELEMENT security-constraint (policy-permission*)>
The security-constraint element is a container for policy-permission elements Examples: <security-constraint> <policy-permission> <role-name>User</role-name> <action-name>view</action-name> </policy-permission> </security-constraint> <security-constraint> <policy-permission> <unchecked/> <action-name>view</action-name> </policy-permission> </security-constraint>Element <!ELEMENT policy-permission (action-name*,unchecked?,role-name*)>
The policy-permission element is used to secure a specific portal page based on a user's role.
Element <!ELEMENT action-name (#PCDATA)>
The role-name element is used to define a role that this security constraint will apply to * <role-name>SOMEROLE</role-name> Access to this portal page is limited to the defined role.Element <!ELEMENT unchecked EMPTY>
The unchecked element is used to define (if present) that anyone can view this portal page
Element <!ELEMENT role-name (#PCDATA)>
The action-name element is used to define the access rights given to the role defined. Possible values are: * view - Users can view the page.
Element <!ELEMENT jboss-app (app-name?)>
<!DOCTYPE jboss-app PUBLIC "-//JBoss Portal//DTD JBoss Web Application 2.6//EN" "http://www.jboss.org/portal/dtd/jboss-app_2_6.dtd">
Element <!ELEMENT app-name (#PCDATA)>
When a web application is deployed, the context path under wich it is deployed is taken as application name. The application name value in this descriptor is used to override it. When a component references a references a portlet, it needs to reference the application too and if the portlet application war file is renammed the reference is not valid anymore. Therefore this tag is used to have an application name that does not depend upon the context path under which the application is deployed.
To define your portal objects (portals, pages, portlet instances, windows, and portlets), you will be using the descriptors found in this section. This section seeks to describe these descriptors. It is recommended you also look at Section 5.2, “Tutorials” and Section 6.4, “Descriptor Examples” for samples on how they are used within a portlet application.
The *-object.xml file is used to define: portal instances, pages, windows, window layout. Additionally, you can also specify the themes and layouts used for specific portal instances, pages, and windows. The description below, only defines a portlet window being added to the default page in the default portal. For advanced functionality, using this descriptor, please read Section 6.4, “Descriptor Examples” .
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
"-//JBoss Portal//DTD Portal Object 2.6//EN"
"http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
<deployments>
<deployment>
<parent-ref>default.default</parent-ref>
<if-exists>overwrite</if-exists>
<window>
<window-name>HelloWorldJSPPortletWindow</window-name>
<instance-ref>HelloWorldJSPPortletInstance</instance-ref>
<region>center</region>
<height>1</height>
</window>
</deployment>
</deployments>
<deployments>...</deployments>
The deployments tag, encapsulates the entire document. You may specify more than one deployment within this tag.
<deployment>...</deployment>
The deployment tag is used to specify object deployments: portals, pages, windows, etc...
<if-exists>...</if-exists>
Possible values are overwrite or keep . Overwrite will destroy the existing object in the database and create a new one, based on the content of the deployment. Keep will maintain the existing object deployment or create a new one if it does not yet exist.
<parent-ref>...</parent-ref>
The parent-ref tag specifies where a particulare object will exist within the portal object tree. In our example, above, we are defining a window and assigning it to default.default , interpreted, this means the window will appear in the default portal and the default page within it.
<window>...</window>
Used to define a portlet window. You will then need to assign to this window, a portlet instance and assign it to a layout region.
<window-name>...</window-name>
A unique name given to this portlet window.
<instance-ref>...</instance-ref>
The portlet instance that this window will represent. It must correspond to the value of instance-id , assigned in your portlet-instances.xml
<region>...</region><height>...</height>
The values are used to specify where this window will appear within the page layout. Region often depends on regions defined in your layout. Height can be any number between 0-X.
The example *-object.xml, above, makes reference to items found in other descriptor files. To help with this topic, we have included a sample image that depicts the relationship:
 |
This is a JBoss Portal specific descriptor that allows a developer to instantiate one-or-many instances of one-or-many portlets. The benefit of using this technique, is to allow one portlet to be instantiated several times with different preference parameters.
Note
Is this descriptor mandatory? Technically, no, as you can deploy your portlet without this descriptor AND without the *-object.xml and then use the management portlet to create instances, assign the instances to windows, and then assign the windows to pages.Our example, below, has us instantiating two separate instances of the NewsPortlet with different preference parameters, one instance will draw a feed for RedHat announcements and the other from McDonalds announcements.
<?xml version="1.0" standalone="yes"?>
<!DOCTYPE deployments PUBLIC
"-//JBoss Portal//DTD Portlet Instances 2.6//EN"
"http://www.jboss.org/portal/dtd/portlet-instances_2_6.dtd">
<deployments>
<deployment>
<instance>
<instance-id>NewsPortletInstance2</instance-id>
<portlet-ref>NewsPortlet</portlet-ref>
<preferences>
<preference>
<name>expires</name>
<value>180</value>
</preference>
<preference>
<name>RssXml</name>
<value>http://finance.yahoo.com/rss/headline?s=rhat</value>
</preference>
</preferences>
<security-constraint>
<policy-permission>
<action-name>view</action-name>
<unchecked/>
</policy-permission>
</security-constraint>
</instance>
</deployment>
<deployment>
<instance>
<instance-id>NewsPortletInstance2</instance-id>
<portlet-ref>NewsPortlet</portlet-ref>
<preferences>
<preference>
<name>expires</name>
<value>180</value>
</preference>
<preference>
<name>RssXml</name>
<value>http://finance.yahoo.com/rss/headline?s=mcd</value>
</preference>
</preferences>
<security-constraint>
<policy-permission>
<action-name>view</action-name>
<unchecked/>
</policy-permission>
</security-constraint>
</instance>
</deployment>
</deployments>
<deployments>...</deployments>
The deployments tag, encapsulates the entire document. You may specify more than one portlet instance deployment, within this tag.
<deployment><instance>...</instance></deployment>
The deployment , and embedded instance tags are used to specify one portlet instance.
<instance-id>...</instance-id>
A unique name given to this instance of the portlet. It must correspond to the value of instance-ref , assigned to the window in your *-object.xml .
<portlet-ref>...</portlet-ref>
The portlet that this instance will represent. It must correspond to the value of portlet-name , assigned in your portlet.xml .
<preferences><preference>...</preference></preferences>
Preferences for this portlet instance are defined here, as type String, in a key-value pair style. It is also possible to specify preferences as type String[], as in:
<preferences> <preference> <name>fruit</name> <value>apple</value> <value>orange</value> <value>kiwi</value> </preference> </preferences><security-constraint> <policy-permission> <action-name>viewrecursive</action-name> <unchecked/> </policy-permission> </security-constraint>The security contraint portion is worth taking a look at, in an isolated fashion. It allows you to secure a specific portlet instance based on a user's role.
Role definition: You must define a role that this security constraint will apply to. Possible values are:
- <unchecked/> Anyone can view this page.
- <role-name>SOMEROLE</role-name> Access to this page is limited to the defined role.
Access Rights: You must define the access rights given to the role defined. Possible values are:
- view Users can view the page.
- viewrecursive Users can view the page and child pages.
- personalize Users are able to view AND personalize the page.
- personalizerecursive Users are able to view AND personalize the page AND its child pages.
The example portlet-instances.xml, above, makes reference to items found in other descriptor files. To help with this topic, we have included a sample image that depicts the relationship:
|
This descriptor is not mandatory, but is useful when having to add JBoss-Specific contexts to your portlet descriptor. It would normally be packaged inside your portlet war, alongside the other descriptors in this section.
<?xml version="1.0" standalone="yes"?>
<!DOCTYPE portlet-app PUBLIC
"-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
"http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd">
<portlet-app>
<portlet>
<portlet-name>ManagementPortlet</portlet-name>
<header-content>
<link rel="stylesheet" type="text/css" href="/images/management/management.css"
media="screen"/>
</header-content>
</portlet>
</portlet-app>The above example will inject a specific style sheet link in the top of the portal page, allowing this portlet to leverage its specific style selectors.
<?xml version="1.0" standalone="yes"?>
<!DOCTYPE portlet-app PUBLIC
"-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
"http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd">
<portlet-app>
<service>
<service-name>UserModule</service-name>
<service-class>org.jboss.portal.identity.UserModule</service-class>
<service-ref>:service=Module,type=User</service-ref>
</service>
</portlet-app>Injects the UserModule service in to the portlet context, allowing a portlet to then leverage the service. For example:
UserModule userModule = (UserModule) getPortletContext().getAttribute("UserModule");
String userId = request.getParameters().getParameter("userid");
User user = userModule.findUserById(userId);
This is the standard portlet descriptor covered by the JSR-168 Specification. It is advisable that developers read the specification items covering proper use of this descriptor, as it is only covered here briefly. For example purposes, we use an editted version of our JBoss Portal UserPortlet definition. Normally, you would package this descriptor in your portlet war.
<?xml version="1.0" encoding="UTF-8"?>
<portlet-app
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd
http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
version="1.0">
<portlet>
<description>Portlet providing user login/logout and profile management</description>
<portlet-name>UserPortlet</portlet-name>
<display-name>User Portlet</display-name>
<portlet-class>org.jboss.portal.core.portlet.user.UserPortlet</portlet-class>
<init-param>
<description>Whether we should use ssl on login and throughout the Portal.
1=yes;0=no</description>
<name>useSSL</name>
<value>0</value>
</init-param>
<supports>
<mime-type>text/html</mime-type>
<portlet-mode>VIEW</portlet-mode>
</supports>
<supported-locale>en</supported-locale>
<supported-locale>fr</supported-locale>
<supported-locale>es</supported-locale>
<resource-bundle>Resource</resource-bundle>
<portlet-info>
<title>User portlet</title>
</portlet-info>
</portlet>
</portlet-app>
<portlet-app>...</portlet-app>
The portlet-app tag, encapsulates the entire document. You may specify more than one portlet, within this tag.
<portlet>...</portlet>
The portlet tag is used to define one portlet that is deployed withing this archive.
<description>...</description>
A verbal description of tis portlet's function.
<portlet-name>...</portlet-name>
The name of this portlet, usually the class name
<portlet-class>...</portlet-class>
The fully-qualified-name of this portlet class.
<init-param><name>...</name><value>...</value></init-param>
Using the init-param tag, you can specify initialization parameters to create initial state inside your portlet class. Normally, they would be used in the portlet's init() method. You can specify more than one init-param.
<supports>...</supports>
Here, you would advertise the supported mime-type and supported portlet-modes for this portlet.
<supported-locale>...</supported-locale>
Here, you would advertise the supported locales for this portlet. You can specify many.
<resource-bundle>...</resource-bundle>
The resource bundle that will back the locales specified.
<portlet-info><title>...</title></portlet-info>
The portlet title that will be displayed in the portlet window's title bar.
Note
This is a simple portlet.xml primer, and is not meant as a replacement for what is covered in the actual Portlet specification.
JBoss Portal requires a Datasource descriptor to be deployed alongside the jboss-portal.sar for access to a database. This section does not explain what a Datasource Descriptor is, but does explain where to obtain some templates that you can configure for your own installation.
Note
For an in-depth introduction to datasources, you can view the JBoss AS documentation online here .
Several template datasource descriptors can be found in the binary and bundle distributions. They are commonly located under the setup directory:
 |
The directory setup should contain the following files, that you can customize for your own Database/Connector:
 |
You will need a valid datasource descriptor, for JBoss Portal to communicate with your database. Having obtained the sources and having set your JBOSS_HOME environment variable ( Section 2.3.2.2, “Operating System Environment Setting” ), you can now have the JBoss Portal build system generate preconfigured datasources for you.
Navigate to JBOSS_PORTAL_HOME_DIRECTORY/core and type:
build datasource
 |
Once complete, the datasource build should produce the following directory and file structure:
 |
At this point, you should configure the one that suits you best with your Database and JDBC driver.
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>PortalDS</jndi-name>
<connection-url>jdbc:postgresql:jbossportal</connection-url>
<driver-class>org.postgresql.Driver</driver-class>
<user-name>portal</user-name>
<password>portalpassword</password>
</local-tx-datasource>
</datasources>Please verify that the username, password, url, and driver-class are correct for your flavor of DB.
By default, JBoss Portal ships with all errors set to display. You can fine-tune this behaviour by modifying some properties in the file, jboss-portal.sar/conf/config.xml :
<!-- When a window has restrictedaccess : show or hide values are permitted --> <entry key="core.render.window_access_denied">show</entry> <!-- When a window is unavailable : show or hide values are permitted --> <entry key="core.render.window_unavailable">show</entry> <!-- When a window produces an error : show, hide or message_only values are permitted --> <entry key="core.render.window_error">message_only</entry> <!-- When a window produces an internal error : show, hide are permitted --> <entry key="core.render.window_internal_error">show</entry> <!-- When a window is not found : show or hide values are permitted --> <entry key="core.render.window_not_found">show</entry>
Either show or hide are allowed as flags in these elements. Depending on the setting and actual error, either an error message is deployed or a full stack trace within the portlet window. Additionally, the core.render.window_error property supports the message_only value. This value will only display the error message whereas show will display the full stack trace if it is available.
By default, when a user logs in, she is forwarded to the default page of the default portal. In order to forward her to her dashboard, it is possible to set in the file jboss-portal.sar/conf/config.xml:
<!-- Namespace to use when logging-in, use "dashboard" to directly
log-in the dashboard otherwise use "default" -->
<entry key="core.login.namespace">dashboard</entry>
This sample application and descriptor will create a new page, named MyPage in your portal. To illustrate our example, we have made available a portlet with a page descriptor that you can download here: HelloWorld Page .
Note
To use this example, simply extract the zip, and deploy the helloworldportalpage.war where your portal is running (hot-deployment supported).Our sample includes a descriptor to define this new portal page, helloworld-object.xml , located under helloworldportalpage.war/WEB-INF/ , and it looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
"-//JBoss Portal//DTD Portal Object 2.6//EN"
"http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
<deployments>
<deployment>
<parent-ref>default</parent-ref>
<if-exists>overwrite</if-exists>
<properties/>
<page>
<page-name>MyPage</page-name>
<security-constraint>
<policy-permission>
<action-name>viewrecursive</action-name>
<unchecked/>
</policy-permission>
</security-constraint>
<window>
<window-name>HelloWorldPortletPageWindow</window-name>
<instance-ref>HelloWorldPortletPageInstance</instance-ref>
<region>center</region>
<height>0</height>
</window>
</page>
</deployment>
</deployments>
A deployment file can be composed of a set of <deployments>. In our example file, above, we are defining a page, placing the portlet as a window on that page, and creating an instance of that portlet. You can then use the Management Portlet (bundled with JBoss Portal) to modify the instances of this portlet, reposition it, and so on...
- <if-exists> Possible values are overwrite or keep . Overwrite will destroy the existing object and create a new one based on the content of the deployment. Keep will maintain the existing objct deployment or create a new one if it does not yet exist.
- <parent-ref> Indicates whether the object should be hooked in to the portal tree.
- <properties> Properties definition specific to this page, commonly used to define the specific theme and layout to use. If not defined, the default portal layouts/theme combination will be used.
- <page> The start of a page definition.
- <page-name> The name of the page.
- <window> The start of a window definition.
- <window-name> The name of the window.
- <instance-ref> The instance reference used by this window. Should correspond with the <instance-name> variable.
- <height> The vertical position of this window within the region defined in the layout.
- <instance> The start of an instance definition. page.
- <instance-name> Maps to the above <instance-ref> variable.
- <component-ref> Takes the name of the application followed by the name of the portlet, as defined in the portlet.xml
<security-constraint> <policy-permission> <action-name>viewrecursive</action-name> <unchecked/> </policy-permission> </security-constraint>The security contraint portion is worth taking a look at, in an isolated fashion. It allows you to secure a specific page/portal based on a user's role.
Role definition: You must define a role that this security constraint will apply to. Possible values are:
- <unchecked/> Anyone can view this page.
- <role-name>SOMEROLE</role-name> Access to this page is limited to the defined role.
Access Rights: You must define the access rights given to the role defined. Possible values are:
- view Users can view the page.
- viewrecursive Users can view the page and child pages.
- personalize Users are able to view AND personalize the page.
- personalizerecursive Users are able to view AND personalize the page AND its child pages.
To illustrate our example, we have made available a portlet that you can download here: HelloPortal .
For our example we make available helloworld-object.xml located under helloworldportal.war/WEB-INF/ , and it looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
"-//JBoss Portal//DTD Portal Object 2.6//EN"
"http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
<deployments>
<deployment>
<parent-ref/>
<if-exists>overwrite</if-exists>
<portal>
<portal-name>HelloPortal</portal-name>
<supported-modes>
<mode>view</mode>
<mode>edit</mode>
<mode>help</mode>
</supported-modes>
<supported-window-states>
<window-state>normal</window-state>
<window-state>minimized</window-state>
<window-state>maximized</window-state>
</supported-window-states>
<properties>
<!-- Set the layout for the default portal -->
<!-- see also portal-layouts.xml -->
<property>
<name>layout.id</name>
<value>generic</value>
</property>
<!-- Set the theme for the default portal -->
<!-- see also portal-themes.xml -->
<property>
<name>theme.id</name>
<value>renaissance</value>
</property>
<!-- set the default render set name (used by the render tag in layouts) -->
<!-- see also portal-renderSet.xml -->
<property>
<name>theme.renderSetId</name>
<value>divRenderer</value>
</property>
</properties>
<security-constraint>
<policy-permission>
<action-name>personalizerecursive</action-name>
<unchecked/>
</policy-permission>
</security-constraint>
<page>
<page-name>default</page-name>
<security-constraint>
<policy-permission>
<action-name>viewrecursive</action-name>
<unchecked/>
</policy-permission>
</security-constraint>
<window>
<window-name>MyPortletWindow</window-name>
<instance-ref>MyPortletInstance</instance-ref>
<region>center</region>
<height>0</height>
</window>
</page>
</portal>
</deployment>
<deployment>
<parent-ref>HelloPortal</parent-ref>
<if-exists>overwrite</if-exists>
<page>
<page-name>foobar</page-name>
<security-constraint>
<policy-permission>
<action-name>viewrecursive</action-name>
<unchecked/>
</policy-permission>
</security-constraint>
<window>
<window-name>MyPortletWindow</window-name>
<instance-ref>MyPortletInstance</instance-ref>
<region>center</region>
<height>0</height>
</window>
</page>
</deployment>
</deployments>
This example, when deployed, will register a new portal instance named HelloPortal with two pages in it. The portal instance can be accessed by navigating to: http://localhost:8080/portal/portal/HelloPortal for the default page, and http://localhost:8080/portal/portal/HelloPortal/foobar , for the second page created.