Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-security-declarative-psml.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-security-declarative-psml.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-security-declarative-psml.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-security-declarative-psml.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,373 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<document> + <properties> + <title>Guide to Declarative Security through PSML</title> + <subtitle>Guide to Declarative Security through PSML</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]"/> + <person name="Randy Watler" email="[email protected]"/> + </authors> + </properties> + <body> +<section name="Security Constraints"> +<p> +<ul> + <li><a href="#The Security Constraint">Security Constraint</a></li> + <li><a href="#Declarative and Global Constraints">Declarative and Global Constraints</a></li> + <li><a href="#Folder Constraints">Folder Constraints</a></li> + <li><a href="#Page Constraints">Page Constraints</a></li> + <li><a href="#Fragment Constraints">Fragment Constraints</a></li> + <li><a href="#Spring Configuration">Spring Configuration</a></li> + <li><a href="../devguide/guide-psml-dtd.html#PSML_DTDs">PSML Document DTDs</a></li> +</ul> +</p> +<p> +Security Constraints are applied to pages and folders. Security Constraints either grant or deny +access to pages and folders. Constraints can be defined in one or all of these four places: +<ul> + <li>1. <b>Global:</b> As declarations in the <b><i>page.security</i></b> file found in the root of the PSML tree.</li> + <li>2. <b>Folder:</b> In the <b><i>folder.metadata</i></b> file optionally located in every directory.</li> + <li>3. <b>Page:</b> In PSML files to constrain access to specific pages.</li> + <li>4. <b>Fragment:</b> In page PSML files to constrain access to a specific fragment within a page.</li> +</ul> +</p> +<subsection name='Grants'> +<p> +Grants are associated with permissions, authorizing, or granting, a principal list +access to a page or folder. +A granting security constraint is the association of a list of one +or more security principals combined with one or more permissions. Grant constraints grant access to a page or folder +for the associated list of permissions. +</p> +</subsection> +<subsection name='Denies'> +<p> +A deny security constraint is declared +with one or more security principals; with no associated permissions. Deny constraints prohibit access +to the page or folder for the given list of principals. Note that deny constraints +must be listed before grant constraints. +</p> +</subsection> +<subsection name='Declarative and Referential Constraints'> +<p> +When working with pages and folder resource constraints, a constraint can be either +a <b><i>declarative constraint</i></b> or a <b><i>referential</i></b> constraint. +Declarative constraints are declared and put to use right in place for the particular +page or folder resource. Where as referential constraints refer to a constraint declared +in a centralized security constraint resource: the <b><i>page.security</i></b> file. Each +site or subsite can have one <b><i>page.security</i></b> resource for declaring constraints +to be referenced in any page or folder. +</p> +</subsection> +</section> +<section name='The Security Constraint'> +<p> +A security constraint is an XML element found in a PSML file, a folder metadata file, or in the global security declarations. +A security constraint has one attribute: the name. A security constraint has the following elements: +</p> +<ul> + <li>roles - a comma-separated list of one or more role principals or * for all roles</li> + <li>groups - a comma-separated list of one or more group principals or * for all groups</li> + <li>users - a comma-separated list of one or more user principals or * for all users</li> + <li>owner - a single user principal</li> + <li>permissions - a comma-separated list of one or permissions (view,edit,help)</li> +</ul> +<p> +The first four elements (roles, groups, users, owner) all define the principals who will either have a permission granted or denied. +</p> +<subsection name='Permissions'> +<p> +Permissions are the portal modes that are granted by the security constraint. Note that permissions are only granted, not denied. +The <b><i>view</i></b> permission is similiar to the <b><i>read</i></b> permission found in operating systems. +The <b><i>edit</i></b> permission is similiar to the <b><i>write</i></b> permission found in operating systems. +The <b><i>help</i></b> permission is similiar to the <b><i>info</i></b> permission found in some portals. +</p> +</subsection> + +<subsection name='Roles'> +<p> +Constraints can be granted to one or more role principals for a set of permissions on a given resource. +Roles are derived from the authorized users list of role principals, i.e. the roles that the user is a member of. +If the authorized user is a member of any of the listed roles, the permission to the resource will be granted. +</p> +<source><![CDATA[ + <security-constraint> + <roles>adminstrator, manager</roles> + <permissions>view, edit</permissions> + </security-constraint> +]]></source> +Constraints can also deny role principals access to the entire resource. +If the authorized user is a member of any of the listed roles, all access to the resource is denied. +<source><![CDATA[ + <security-constraint> + <roles>adminstrator, manager</roles> + </security-constraint> +]]></source> +</subsection> +<subsection name='Groups'> + <p> +Constraints can be granted to one or more group principals for a set of permissions on a given resource. +Groups are derived from the authorized users list of group principals, i.e. the groups that the user is a member of. +If the authorized user is a member of any of the listed groups, the permission to the resource will be granted. +<source><![CDATA[ + <security-constraint> + <groups>accounting, development</groups> + <permissions>view</permissions> + </security-constraint> +]]></source> +Constraints can also deny group principals access to the entire resource. +If the authorized user is a member of any of the listed groups, all access to the resource is denied. +<source><![CDATA[ + <security-constraint> + <groups>accounting, development</groups> + </security-constraint> +]]></source> +</p> +</subsection> +<subsection name='Users'> + <p> +Constraints can be granted to one or more user principals for a set of permissions on a given resource: +The current user must be one of the listed principals in the comma-separated list in order to grant permission to the resource. +<source><![CDATA[ + <security-constraint> + <users>joey, deedee, johnny</users> + <permissions>view, edit, help</permissions> + </security-constraint> +]]></source> +Constraints can also deny user principals access to the entire resource. +If the authorized user is in the list, all access to the resource is denied. +<source><![CDATA[ + <security-constraint> + <users>fred</users> + </security-constraint> +]]></source> +</p> +</subsection> +<subsection name='Combinations'> +<p> +Note that you can grant or deny permissions to a collection of one or more principal types. For example, here we grant view and edit permissions +to the roles (manager, developer), and to the groups (QA and Research), and to the particular user (dilbert): +If the authorized user is a member of any of the listed roles, groups, or users, the permission to the resource will be granted. +</p> +<source><![CDATA[ + <security-constraint> + <roles>hacker, coder, guru</roles> + <groups>unix, linux, freebsd</groups> + <users>betty, fred, barney, wilma</users> + <permissions>view, edit</permissions> + </security-constraint> +]]></source> +<p> +Constraints can also deny combinations of principals access to the entire resource. +If the authorized user is a member of any of the listed groups, roles or users, all access to the resource is denied. +</p> +<source><![CDATA[ + <security-constraint> + <roles>hacker, coder, guru</roles> + <groups>unix, linux, freebsd</groups> + <users>betty, fred, barney, wilma</users> + </security-constraint> +]]></source> +</subsection> +<subsection name='All *'> +<p> +The * can be applied to roles, groups, users or permissions to imply ALL. +<source><![CDATA[ + <security-constraint> + <users>*</users> + <permissions>*</permissions> + </security-constraint> +]]></source> +</p> +</subsection> +<subsection name='Owner'> +<p> +Resource owners are declared as a security constraint. Owning principals are automatically granted ALL permissions. +<source><![CDATA[ + <owner>dilbert</owner> +]]></source> +</p> +</subsection> +</section> +<section name='Declarative and Global Constraints'> +<p> +Declarative constraints are defined in the <b><i>page.security</i></b> file of the root of a site. +Declarative constraints are referenced in pages and folders with the <b><i>security-constraints-ref</i></b> tag. +Global constraints are also declarative constraints. They are also defined and found in the <b><i>page.security</i></b> file in the root PSML repository. +The difference with global constraints is that they implicitly apply to all folders and pages within the scope of the page.security file, (i.e. the site). +Note that there can be only one <b><i>page.security</i></b> file in a Jetspeed installation. +<source><![CDATA[ + <security-constraints-def name="admin"> + <security-constraint> + <roles>admin</roles> + <permissions>view, edit</permissions> + </security-constraint> + </security-constraints-def> + <global-security-constraints-ref>admin</global-security-constraints-ref> +]]></source> +Constraint names are limited to letters, numbers, "_", "-", and "." characters. +</p> +<subsection name='Constraints Reference Expressions'> +<p> +In addition to constraint reference by name, the <b><i>security-constraints-ref</i></b> and <b><i>global-security-constraints-ref</i></b> tags accept +logical expressions with constraint reference operands to express more complex grants. Expressions are normally employed when the default "OR" grant +logic of security constraints lists becomes awkward or alternative logic such as "AND" or "NOT" is required. +<source><![CDATA[ + <global-security-constraints-ref>admin and noc</global-security-constraints-ref> +]]></source> +<source><![CDATA[ + <security-constraints-ref>(support || engineering) && !marketing</security-constraints-ref> +]]></source> +Expressions are infix and support the following operators: "and", "or", "not", "(", ")", "&&", "||" and "!". The usual operator precedence rules for +logical expressions apply. +</p> +</subsection> +<subsection name='Default Constraints'> +<p> + Several security constraint declarations are made in the default deployment of Jetspeed: +<table> + <tr> + <th>name</th> + <th>grants</th> + <th>permissions</th> + <th>global</th> + </tr> + <tr> + <td>admin</td> + <td>roles: admin</td> + <td>view, edit</td> + <td>yes</td> + </tr> + <tr> + <td>manager</td> + <td>roles: manager</td> + <td>view</td> + <td>no</td> + </tr> + <tr> + <td>users</td> + <td>roles: user, manager</td> + <td>view</td> + <td>no</td> + </tr> + <tr> + <td>public-view</td> + <td>users: *</td> + <td>view</td> + <td>no</td> + </tr> + <tr> + <td>public-edit</td> + <td>users: *</td> + <td>view, edit</td> + <td>no</td> + </tr> +</table> +</p> +</subsection> +</section> +<section name='Folder Constraints'> +<p> +Folder Security constraints are placed in a <b><il>security-constraints list</il></b> in the <b><i>folder.metadata</i></b> file optionally found in each folder in the site. +Note that the absence of a <b><i>folder.metadata</i></b> or security constraints within that file means that the folder will +inherit the constraints of the parent folder, all the way up to the root folder of the site or subsite. Folder constraints do +not inherit across subsites. Folder security constraints are made up of declarative security constraints and referential security +constraints. Here is an example of both, the first being a referential constraint, the second a declarative constraint: +<source><![CDATA[ + <security-constraints> + <security-constraints-ref>public-view</security-constraints-ref> + <security-constraint> + <groups>engineering</groups> + <permissions>view</permissions> + </security-constraint> + </security-constraints> +]]></source> +</p> +<p> +Note that all security constraints must be placed within a <b><i>security-constraints</i></b> collection. +</p> +</section> +<section name='Page Constraints'> +<p> +Page Security constraints are placed <b><il>security-constraints list</il></b> +in <b><i>PSML</i></b> files and are optional. +Note that the absence of a security constraints list within that file means that the folder will +inherit the constraints of the folder in which it resides. Page security constraints are made up of +declarative security constraints and referential security +constraints. Here is an example of both, the first being a referential constraint, the second a declarative constraint: +</p> +<source><![CDATA[ + <security-constraints> + <security-constraints-ref>global-view</security-constraints-ref> + <security-constraint> + <groups>accounting</groups> + <permissions>view, edit</permissions> + </security-constraint> + </security-constraints> +]]></source> +<p> +Note that all security constraints must be placed within a <b><i>security-constraints</i></b> collection. +</p> +</section> +<section name='Fragment Constraints'> +<p> +As with Page Security constraints, Fragment Security constraints are placed within +<b><il>security-constraints list</il></b> in <b><i>PSML</i></b> page files and are +again optional. As expected, the absence of a security constraints list implies the +fragment will inherit the constraints of the page of which it is a part. Note that +only the view permission is checked against these constraints. Other permissions +are tested only against the containing page. +</p> +</section> +<section name='Portlet Constraints'> +<p>Globally, these are set for a portlet or its portlet application using the administration interface or in the applications's <b><i>jetspeed-portlet.xml</i></b>. See Portal Components - Registry.</p> +<p>However, these global security constraints are not checked by default at render time for 'view', allowing 'view' if the user can see the portlet's containing page.</p> +<p>Security therefore relies on constraining access to folders and pages, controlling who can add portlets and where, and constraining access to portlet instances on a page individually by their containing fragments.</p> + +<p>To enable render-time security constraint checking as an extra catch-all, see Portal Components - Registry.</p> +</section> +<section name="Spring Configuration"> +<p> +Declarative Security Constraints are enabled by default in the Spring configuration of the +Page Manager component. Here is the default Page Manager bean configuration from the +<b><i>page-manager.xml</i></b> spring assembly configuration file: +</p> +<source><![CDATA[ + <bean id="org.apache.jetspeed.page.PageManager" + name="pageManager" + class="org.apache.jetspeed.page.psml.CastorXmlPageManager"> + <constructor-arg index="0"><ref bean="IdGenerator"/></constructor-arg> + <constructor-arg index="1"><ref bean="DocumentHandlerFactory"/></constructor-arg> + <constructor-arg index="2"><ref bean="FolderHandler"/></constructor-arg> + <constructor-arg index="3"><ref bean="PageFileCache"/></constructor-arg> + <!-- permissions security enabled flag, default=false --> + <constructor-arg index="4"><value>false</value></constructor-arg> + <!-- constraints security enabled flag, default=true --> + <constructor-arg index="5"><value>true</value></constructor-arg> + </bean> +]]></source> +<p> +Here the 6th, (index="5"), boolean constructor argument specifies whether or +not the "constraints security" model is enabled. If the Declarative Security Constraints +are not enabled, all inline, referenced, and global security constraints will be ignored. +</p> +</section> + +</body> +</document>
Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-services.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-services.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-services.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-services.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,217 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<document> + <properties> + <title>Jetspeed 2 Services</title> + <subtitle>Guide to Jetspeed Services</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Services"> + <p> + Jetspeed provides a way for portlets to access Jetspeed components, + or services, from a portlet. Although this is a Jetspeed-specific + feature, it is how Jetspeed Administrative portlets can work with + customizing Jetspeed. For example, the Group Administration + portlet below uses a Jetspeed service to manipulate Jetspeed groups. + </p> + <p> + All services must be exported by Jetspeed in the Spring configuration <strong><code>jetspeed-services.xml</code></strong> file. + All services required by a portlet must be + specified in the <strong><code>jetspeed-portlet.xml</code></strong>. + </p> + <p> + Portlet applications requiring a jetspeed service + refer to that service in their <strong><code>jetspeed-portlet.xml</code></strong> deployment descriptor: +<source><![CDATA[ +<js:services> + <js:service name='ApplicationServerManager'/> + <js:service name='PageManager'/> + <js:service name='PermissionManager'/> + <js:service name='PortalAdministration'/> + <js:service name='UserManager'/> +</js:services> +]]></source> + </p> + <p> + Applications can get the service in the portlet init phase, for example: +<source><![CDATA[ +groupManager = (GroupManager) +getPortletContext().getAttribute(CommonPortletServices.CPS_GROUP_MANAGER_COMPONENT); +]]></source> + </p> + <p> + <table> + <tr> + <th colspan="2">Key Jetspeed Services defined in Spring (see jetspeed-services.xml for full list)</th> + </tr> + <tr> + <th>Entry Key</th> + <th>Ref Bean</th> + </tr> + <tr> + <td>PortletRegistryComponent</td> + <td>org.apache.jetspeed.components.portletregistry.PortletRegistry</td> + </tr> + <tr> + <td>SearchComponent</td> + <td>org.apache.jetspeed.search.SearchEngine</td> + </tr> + <tr> + <td>PAM</td> + <td>PAM</td> + </tr> + <tr> + <td>UserManager</td> + <td>org.apache.jetspeed.security.UserManager</td> + </tr> + <tr> + <td>PageManager</td> + <td>org.apache.jetspeed.page.PageManager</td> + </tr> + <tr> + <td>RoleManager</td> + <td>org.apache.jetspeed.security.RoleManager</td> + </tr> + <tr> + <td>GroupManager</td> + <td>org.apache.jetspeed.security.GroupManager</td> + </tr> + <tr> + <td>Profiler</td> + <td>org.apache.jetspeed.profiler.Profiler</td> + </tr> + <tr> + <td>SSO</td> + <td>org.apache.jetspeed.sso.SSOProvider</td> + </tr> + <tr> + <td>EntityAccessor</td> + <td>org.apache.jetspeed.components.portletentity.PortletEntityAccessComponent</td> + </tr> + <tr> + <td>WindowAccessor</td> + <td>org.apache.jetspeed.container.window.PortletWindowAccessor</td> + </tr> + <tr> + <td>ApplicationServerManager</td> + <td>org.apache.jetspeed.tools.pamanager.servletcontainer.ApplicationServerManager</td> + </tr> + <tr> + <td>PortletFactory</td> + <td>portletFactory</td> + </tr> + <tr> + <td>DeploymentManager</td> + <td>deploymentManager</td> + </tr> + <tr> + <td>IdGenerator</td> + <td>IdGenerator</td> + </tr> + <tr> + <td>Powertools</td> + <td>Powertools</td> + </tr> + <tr> + <td>HeaderResource</td> + <td>org.apache.jetspeed.headerresource.HeaderResourceFactory</td> + </tr> + <tr> + <td>TemplateLocator</td> + <td>TemplateLocator</td> + </tr> + <tr> + <td>DecorationLocator</td> + <td>DecorationLocator</td> + </tr> + <tr> + <td>DecorationFactory</td> + <td>DecorationFactory</td> + </tr> + <tr> + <td>Desktop</td> + <td>JetspeedDesktop</td> + </tr> + <tr> + <td>PermissionManager</td> + <td>org.apache.jetspeed.security.PermissionManager</td> + </tr> + <tr> + <td>PortalStatistics</td> + <td>PortalStatistics</td> + </tr> + <tr> + <td>PortalAdministration</td> + <td>PortalAdministration</td> + </tr> + <tr> + <td>PreferencesProvider</td> + <td>org.apache.jetspeed.prefs.PreferencesProvider</td> + </tr> + <tr> + <td>org.apache.jetspeed.container.session.PortalSessionsManager</td> + <td>org.apache.jetspeed.container.session.PortalSessionsManager</td> + </tr> + <tr> + <td>SecurityAccessController</td> + <td>org.apache.jetspeed.security.SecurityAccessController</td> + </tr> + <tr> + <td>PortletTrackingManager</td> + <td>org.apache.jetspeed.aggregator.PortletTrackingManager</td> + </tr> + <tr> + <td>PortalAuthenticationConfiguration</td> + <td>org.apache.jetspeed.administration.PortalAuthenticationConfiguration</td> + </tr> + <tr> + <td>PortalConfiguration</td> + <td>PortalConfiguration</td> + </tr> + <tr> + <td>ImporterManager</td> + <td>importerCastorPageManager</td> + </tr> + <tr> + <td>decorationContentCache</td> + <td>decorationContentCache</td> + </tr> + <tr> + <td>portletContentCache</td> + <td>portletContentCache</td> + </tr> + <tr> + <td>AuditActivity</td> + <td>org.apache.jetspeed.audit.AuditActivity</td> + </tr> + <tr> + <td>JetspeedSerializerFactory</td> + <td>org.apache.jetspeed.serializer.JetspeedSerializerFactory</td> + </tr> + <tr> + <td>PasswordEncodingService</td> + <td>org.apache.jetspeed.security.PasswordEncodingService</td> + </tr> + </table> + </p> + </section> + </body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-tomcat-sso-cross-context-j2-realm.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-tomcat-sso-cross-context-j2-realm.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-tomcat-sso-cross-context-j2-realm.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-tomcat-sso-cross-context-j2-realm.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,102 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<document> + <properties> + <title>Tomcat SSO and Cross Context Webapps Guide</title> + <subtitle>Documentation for using the Jetspeed Authentication accross multiple webapps running in the same Tomcat container</subtitle> + <authors> + <person name="Philip Mark Donaghy" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Sharing the Jetspeed Realm Across Tomcat Webapps"> + <p> + This guide provides a tutorial for creating a shared authentication Realm + between multiple webapps running in the same Tomcat(>=6) container. + </p> + <subsection name="1. The Jetspeed Realm"> + <p> + Realms are configured in the Engine element of $CATALINA_HOME/conf/server.xml. Move the Jetspeed Realm element from $CATALINA_HOME/conf/Catalina/localhost/jetspeed.xml to $CATALINA_HOME/conf/server.xml replacng or commenting out the UserDatabase Realm. + <source><![CDATA[ +<Realm className="org.apache.catalina.realm.JAASRealm" + appName="Jetspeed" + userClassNames="org.apache.jetspeed.security.impl.UserPrincipalImpl" + roleClassNames="org.apache.jetspeed.security.impl.RolePrincipalImpl" + useContextClassLoader="false" + debug="0"/>]]> + </source> + </p> + </subsection> + <subsection name="2. Enable the Tomcat SingleSignOn Valve"> + <p> + Uncomment the Tomcat single sign on Valve in $CATALINA_HOME/conf/server.xml. + <source><![CDATA[ +<Host name="localhost" appBase="webapps"> + <!-- Enable tomcat SSO *** --> + <Valve className="org.apache.catalina.authenticator.SingleSignOn" /> +</Host>]]> + </source> + </p> + </subsection> + <subsection name="3. Each web.xml"> + <p> + Create a security-constraint in each webapp web.xml descriptor. + <source><![CDATA[ + <security-constraint> + <web-resource-collection> + <web-resource-name>Whatever</web-resource-name> + <url-pattern>/*</url-pattern> + </web-resource-collection> + <auth-constraint> + <role-name>manager</role-name> + </auth-constraint> + </security-constraint> + + <!-- Define the Login Configuration for this Application --> + <login-config> + <auth-method>BASIC</auth-method> + <realm-name>Jetspeed</realm-name> + </login-config> + + <!-- Security roles referenced by this web application --> + <security-role> + <description> + The role that is required to log in to the Manager Application + </description> + <role-name>manager</role-name> + </security-role>]]> + </source> + </p> + </subsection> + <subsection name="4. Known Issues"> + <p> + 1. The default Tomcat Realm must be replaced, removed, or commented out. A known side effect of this prevents the Tomcat manager application from working. It can be resolved by using the Jetspeed realm in $CATALINA_HOME/server/webapps/manager/manager.xml. + <source><![CDATA[ + <login-config> + <auth-method>BASIC</auth-method> + <realm-name>Jetspeed</realm-name> + </login-config>]]> + </source> + </p> + <p> + 2. Authentication must be made in Jetspeed before accessing other webapps. + </p> + </subsection> + </section> + </body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-tomcat.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-tomcat.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-tomcat.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-tomcat.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,348 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<document> + <properties> + <title>Apache Tomcat Overview</title> + <subtitle>Documentation on How to Download Jetspeed-2</subtitle> + <authors> + <person name="David Le Strat" email="[email protected]" /> + <person name="David Sean Taylor" email="[email protected]" /> + </authors> + </properties> +<body> +<section name="Apache Tomcat Overview"> +<p> +<a href='http://tomcat.apache.org/'>Apache Tomcat</a> is an implementation of the Java Servlet and JavaServer Pages technologies. + The Java Servlet and JavaServer Pages specifications are developed under the Java Community Process. Although Tomcat is not a full Java Enterprise Application Server, + such as <a href='http://geronimo.apache.org/'>Geronimo</a> or <a href='http://jboss.org/'>JBoss</a>, Tomcat + still has many advanced features of an applications server. Tomcat is not an portal server nor is it portlet container. Jetspeed is both a portal server and includes a portlet container. + To find out more about portlet containers, see the <a href='http://portals.apache.org/pluto/'>Pluto project</a>. + The Jetspeed installer comes with a pre-packaged release of Tomcat built-in.</p> +<subsection name="Tomcat Versions Supported"> +<p> +Jetspeed 2.3.0 is well tested and integrated to run on the following Apache Tomcat platforms: +</p> +<ul> +<li>Latest Tomcat 7.0.59+ - recommended for Servlet API 3.0.1 / JSP 2.2.1</li> +</ul> +</subsection> +<subsection name="How Jetspeed runs in Tomcat"> +<p> +Jetspeed is a normal web application, thus it runs in Tomcat like any other web application. +However, since Jetspeed is also a portal server, with the ability to include content from other deployed portlet applications in the application server, + it has a few special requirements in order for it to run in Tomcat: +</p> +<ul> +<li>Cross Context Invocation - Jetspeed must be configured in Tomcat to execute cross-context request dispatching.</li> +<li>Database Configuration - By default, Jetspeed lets Tomcat manage the database connections. Tomcat requires a context file be provided in order for Jetspeed to use Tomcat connection pooling</li> +<li>Common Class Loader - Jetspeed requires loading several jars in Tomcats shared class loader. The classes from these jars are shared between Jetspeed and all portlet applications</li> +<li>Renaming the Context Path - you can give Jetspeed a different context path name</li> +<li>Configuring a JAAS Realm - you can configure JAAS Realm features in Tomcat specific to Jetspeed like providing your own role and user classes</li> +</ul> +<p> +Getting Jetspeed to run in Tomcat requires some minimal configuration describing in the following section. If you run the Jetspeed installer, which comes with Tomcat built-in, +all the configuration is managed by the installer program for you. +</p> +</subsection> +</section> +<section name="Tomcat Configuration"> +<p>Tomcat uses XML files to configure Tomcat-specific features as well as standardized features. The <i>WEB-INF/web.xml</i> file configures the standard features. Some Tomcat specific features for web applications, +not explicity covered by the servlet specification, are configured in the <i>META-INF/context.xml</i> file. Several of +Tomcat specific configurations required to configure Jetspeed without the installer are: database, cross-context requests, and the common-class-loader. +Also note, If you build Jetspeed using the Maven build tools, Jetspeed will create this Tomcat context file for the Jetspeed web application and deploys it to Tomcat automatically. +</p> +<p>Here is an example of a context.xml file for Jetspeed:</p> +<source> +<![CDATA[ +<Context crossContext="true"> + + <Realm className="org.apache.catalina.realm.JAASRealm" + appName="Jetspeed" + userClassNames="org.apache.jetspeed.security.impl.UserPrincipalImpl" + roleClassNames="org.apache.jetspeed.security.impl.RolePrincipalImpl" + useContextClassLoader="true" + debug="0"/> + + + <Resource name="jdbc/jetspeed" auth="Container" + factory="org.apache.commons.dbcp.BasicDataSourceFactory" + type="javax.sql.DataSource" username="j2" password="secret" + driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost/jetdb" + maxActive="100" maxIdle="30" maxWait="10000"/> + + <Valve className="org.apache.catalina.authenticator.FormAuthenticator" characterEncoding="UTF-8"/> + +</Context> +]]> +</source> +<subsection name='Tomcat Cross-Context Configuration'> +<p> +First thing you will notice about the Tomcat context file is the cross context setting set to true, which is *not* the default: +</p> +<source> +<![CDATA[ +<Context crossContext="true"> +]]> +</source> +<p> +This setting is required for Jetspeed to "aggregate" content from different portlet applications all onto the same page. But default, Tomcat does not enable this feature. +Please make sure this setting is true, or Jetspeed will not function properly. +</p> +<img src='images/dispatch.jpg'/> +</subsection> +<p> +</p> +<subsection name='Tomcat Database Configuration'> +<p> + This context file also holds the JDBC configuration for the database used by Jetspeed internally. By default, Jetpeed looks up database connections with JNDI. + Thus Jetspeed expects you that you configure your database connections in your particular application server configuration. In the case of Tomcat, here + is the database configuration necessary to setup a required JNDI resource name <i>jdbc/jetspeed</i>: + </p> +<source> +<![CDATA[ +<Context crossContext="true"> + +... + <Resource name="jdbc/jetspeed" auth="Container" + factory="org.apache.commons.dbcp.BasicDataSourceFactory" + type="javax.sql.DataSource" username="j2" password="secret" + driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost/jetdb" + maxActive="100" maxIdle="30" maxWait="10000"/> + +... + +</Context> +]]> +</source> +<p>We have configured several important features of the database configuration specific to Tomcat including:</p> +<table> +<tr><th>attribute</th><th>description</th></tr> +<tr> + <td>factory</td> + <td>The JDBC Data Source Factory class name. Here we make use of the Apache Commons DBCP (Database Connection Pooling) library</td> +</tr> +<tr> + <td>type</td> + <td>javax.sql.DataSource - the type of resource: a JDBC DataSource provider</td> +</tr> +<tr> + <td>username</td> + <td>The username in the database that will be used to authenticate</td> +</tr> +<tr> + <td>password</td> + <td>The password of the user on the database</td> +</tr> +<tr> + <td>driverClassName</td> + <td>The classname of the JDBC database driver: specific to the database being used by Jetspeed</td> +</tr> +<tr> + <td>url</td> + <td>The JDBC Database connection URL string</td> +</tr> +<tr> + <td>maxActive</td> + <td>Maximum number of active database connections</td> +</tr> +<tr> + <td>maxIdle</td> + <td>Maximum number of idle database connections</td> +</tr> +<tr> + <td>maxWait</td> + <td>Maximum wait time to get a connection in milliseconds before timing out</td> +</tr> +</table> +<p>Also see the Tomcat documentation for more details on configuring +<a href='https://tomcat.apache.org/tomcat-7.0-doc/jndi-datasource-examples-howto.html'>database connection pools</a> +and <a href='https://tomcat.apache.org/tomcat-7.0-doc/jndi-resources-howto.html'>JNDI</a> in Tomcat</p> +</subsection> +<subsection name='Common Class Loader in Tomcat shared/lib'> +<p> +Jetspeed requires loading several jars in Tomcats shared class loader. The classes from these jars are shared between Jetspeed and all portlet applications. +</p><p> +Jetspeed and portlet applications are deployed as separate web +applications. Jetspeed runs as a MVC-Controller-type servlet, running +in a standalone web(portlet) application. Each portlet application runs +in its own web application. The Portal then dispatches to portlets using +cross-context invocation +</p><p> +This means that parts of Jetspeed +must exist in common class loaders shared amongst all web +applications in the application server. As the diagram below depicts, the shared/lib class loader takes precedence over the individual portlet application class loaders: +</p> +<img src='images/sharedlib.jpg'/> +<p>To summarize, you must place the following jars in Tomcat's shared library directory (lib):</p> +<source> +ls $TOMCAT_HOME/lib +... +apa-logging-1.1.jar +ccpp-1.0.jar +jetspeed-api-2.3.0.jar +jetspeed-commons-2.3.0.jar +pluto-container-api-2.0.3.jar +pluto-taglib-2.0.3.jar +portals-bridges-common-2.1.jar +portlet-api_2.1.0_spec-1.0.jar +</source> +<p>Additionally, you may want to put your JDBC driver here, for example:</p> +<source> +mysql-connector-java-5.1.6-bin.jar +</source> +</subsection> +</section> +<section name='Deploying Portlet Applications to Tomcat'> +<p> +Portlets are similar to servlets. They require a deployment descriptor, called the <i>portlet.xml</i> placed in the WEB-INF directory in addition to the <i>web.xml</i> required by servlet applications. +Portlet Applications need to be packaged in the same <i>WAR</i> format specified for servlets. In order to deploy a portlet, Jetspeed-2 requires the user to follow those steps: +<ul> +<li>Build your portlets as a portlet application just as you would a web application.</li> +<li>Package your portlet application into a .war file, along with a WEB-INF/portlet.xml descriptor.</li> +<li>Copy the .war file to Jetspeed's deployment directory, by default this is <i>WEB-INF/deploy</i>. Jetspeed will take care of automatically +deploying the portlet application into the application server (Tomcat), and then registering the portlets into the portlet registry. +</li> +</ul> +</p> +<p> +Alternatively, you can copy directly into Tomcat's <i>webapps</i> directory, but only if you have <i>infused</i> your portlet application with the necessary settings in your web.xml. +</p> +<p> +You can also copy over a portlet-application's web.xml or +portlet.xml to cause re-registration of the portlet application. +</p> +<subsection name='Infusing Jetspeed Servlet in your Application'> +<p> +Jetspeed requires that a Jetspeed Container servlet be placed in your portlet application's web.xml. This servlet's class file is actually stored in the Jetspeed shared library path, so you +do not have to include it into your portlet application distribution. Again, when dropping into Jetspeed's deploy directory, this procedure is not necessary, as the servlet +will be automatically added to your web.xml by the Jetspeed deployer. This servlet allows +Jetspeed to communicate with your portlet application to invoke cross-context portlet +phases (action, render). Additionally, the servlet will attempt to register this portlet +application during the servlet initialization phase. A check-sum value on the portlet.xml, +web.xml, and jetspeed-portlet.xml is compared for changes, determining if re-registration is necessary. +</p> +<source> +<![CDATA[ + <servlet> + <description>MVC Servlet for Jetspeed Portlet Applications</description> + <display-name>Jetspeed Container</display-name> + <servlet-name>JetspeedContainer</servlet-name> + <servlet-class>org.apache.jetspeed.container.JetspeedContainerServlet</servlet-class> + <init-param> + <param-name>contextName</param-name> + <param-value>j2-admin</param-value> + </init-param> + <load-on-startup>100</load-on-startup> + </servlet> + + <servlet-mapping> + <servlet-name>JetspeedContainer</servlet-name> + <url-pattern>/container/*</url-pattern> + </servlet-mapping> +]]> +</source> +<p>The <i>contextName</i> init parameter defines the context path used by Tomcat and Jetspeed in locating your application. This should be the same as your servlet context path setting for Tomcat.</p> +<p>Finally, you have the option to run the Jetspeed deploy tool to automatically add the above XML to your application's web.xml. Jetspeed provides a Deploy Tool to run during +the build process of your portlet application:</p> +<source> +<![CDATA[ + java -jar jetspeed-deploy-tools-<version>.jar -s inputWarPath outputWarPath + + where: + + -s: flag indicating whether or not to strip to loggers from the application. When the flag is + present, the loggers available in the application will be removed. + + inputWarPath: the path of the war to process. + outputWarPath: the path of the processed war. +]]> +</source> +</subsection> +<subsection name='Tomcat Manager and Jetspeed'> +<p> +Jetspeed knows how to communicate with the Tomcat Manager application. The Tomcat Manager is a simple programmatic API for managing servlet application lifecycle including:</p> +<ul> +<li>Deploy an application</li> +<li>Undeploy an application</li> +<li>Start an application</li> +<li>Stop an application</li> +</ul> +<p> +The Jetspeed PortletApplicationManager portlet requires some Tomcat configuration modifications before it can work correctly. You will need to define an manager-script user in Tomcat's <i>conf/tomcat-users.xml</i>. +Make sure to configure your user with the <i>manager-script</i> role. +</p> +<p> +A minimal example tomcat-users.xml can look like: + <source> + <![CDATA[ +<tomcat-users> + <role rolename="manager-script"/> + <user username="j2deployer" password="xxxxx" roles="manager-script"/> +</tomcat-users>]]> + </source> + <i> + The attribute values for username and password must also be configured in the <a href='config-overrides.html'>Jetspeed Override Properties</a> + </i> + </p> +</subsection> +</section> +<section name='Advanced Configuration...'> +<subsection name="Changing the Application Context Path and Docbase"> +<p>If you would like, you can change the context path and document base of any web or portlet application, including Jetspeed. +The context path is the path that identifies the application, such as /jetspeed in a URL like http://localhost:8080/jetspeed/portal. +With this feature you can change the name of your portal to say something like <i>/myportal</i>: +</p> +<source> +<![CDATA[ +<Context path='/myportal' docBase='/opt/myportal'> +]]> +</source> +<p>Additionally, your application doesn't have to reside in the Tomcat webapps directory. In the example above we have moved it to the /opt/myportal directory. +</p> +</subsection> +<subsection name="JAAS Realms, Users and Roles"> +<p>Jetspeed makes use of its own login module. In that login module, Jetspeed provides its own implementations of User Principals and Role Principals to Tomcat. +In order for Tomcat to know about these JAAS (Java Authentication and Authorization Services) classes, we need to tell Tomcat:</p> +<source> +<![CDATA[ + <Realm className="org.apache.catalina.realm.JAASRealm" + appName="Jetspeed" + userClassNames="org.apache.jetspeed.security.impl.UserPrincipalImpl" + roleClassNames="org.apache.jetspeed.security.impl.RolePrincipalImpl" + useContextClassLoader="true" + debug="0"/> +]]> +</source> +</subsection> +<subsection name="Tomcat on Windows"> + <p> + To have redeployment and undeployment working + properly when using Tomcat 7.x+ on Windows you have + to set the global Context attribute "antiJARLocking" + to true in the <i>context.xml</i> file under META-INF. + </p> + <source> + <![CDATA[ + <Context antiJARLocking="true"> + ... + </Context>]]> + </source> +</subsection> +</section> +</body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-transactions.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-transactions.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-transactions.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-transactions.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,140 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<document> + <properties> + <title>Jetspeed 2 Transactions</title> + <subtitle>Guide to Jetspeed Transactions</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Jetspeed Transactions Configuration"> + <p>All Jetspeed components that use the database are transactional. This guide helps you learn about how Jetspeed components are + wired together in the context of Spring transactions. When deploying Jetspeed, you may need to modify some of the componnents that + are transactional. This guide will help you understand how to configure transactional beans (services) in Jetspeed.</p> + <subsection name="Transactions in Spring"> + <p> + Transactions allow you to group several operations into a single unit of work that either fully happens or fully doesn't happen. + Jetspeed leverages the Spring Framework to make its components transactional. The Spring Framework provides the transaction management + required to execute transactions across two or more Jetspeed components. Jetspeed transactions are configured as declarative transactions. + Jetspeed currently does not make use of programmatic transactions. The Spring Framework provides the declarative transaction management + through Spring's AOP framework. Spring provides three ways to declare transactional boundaries in the spring configuration. + <ol> + <li>Spring Transactional Interceptors, Bean Wrapping</li> + <li>XML declared transactions</li> + <li>Annotations</li> + </ol> + Jetspeed uses the original Spring transactional support (1): wrapping Jetspeed components with transactional interceptors. + When configuring beans in Java, be aware that any bean that uses a database is going to be wrapped with a transactional wrapper. + The transaction advice is handled in the transaction interceptor. When injecting dependencies, the transaction interceptor, + not the actual Jetspeed service implementation, is injected as a dependency into other Jetpeed services. + </p> + </subsection> + <subsection name="Declarative Transactions via Interception"> + <p> + Lets take one example of a transaction Jetspeed service: the Permission Manager service. This service is configured in the <strong><code>security-managers.xml</code></strong> file. + The first bean is actually named with a <code>Impl</code> suffix. This is because this is the <strong>implementation</strong> bean: + the bean name <code>org.apache.jetspeed.security.impl.PermissionManagerImpl</code> is the same name as the class. Class attributes + represent the class name of the implementing class. + </p> + <p> + The second bean is named by interface: <code>org.apache.jetspeed.security.PermissionManager</code>. This bean is not the actual + Permission implementation. The bean definition is a transactional proxy: it is an bean wrapper or interceptor. When wiring the + Permission Manager to another Jetspeed service, make sure to use the proxy object, not the actual implementation. This ensures + that declarative transaction support in Spring can intercept calls to the Permission Manager. + </p> + <p>Notice that the parent bean is <code>baseTransactionProxy</code>. This is how we get the transactional support: through Spring AOP + inheriting the base functionality for proxying transactions declaratively. + </p> + <p> +<source><![CDATA[ + <!-- Security: Permission Manager --> + <bean id="org.apache.jetspeed.security.impl.PermissionManagerImpl" + class="org.apache.jetspeed.security.impl.PermissionManagerImpl" /> + + <bean id="org.apache.jetspeed.security.PermissionManager" parent="baseTransactionProxy" + name="permissionManager" > + <property name="proxyInterfaces"> + <value>org.apache.jetspeed.security.PermissionManager</value> + </property> + <property name="target"> + <ref bean="org.apache.jetspeed.security.impl.PermissionManagerImpl"/> + </property> + <property name="transactionAttributes"> + <props> + <prop key="remove*">PROPAGATION_REQUIRED</prop> + <prop key="grant*">PROPAGATION_REQUIRED</prop> + <prop key="revoke*">PROPAGATION_REQUIRED</prop> + <prop key="grant*">PROPAGATION_REQUIRED</prop> + <prop key="add*">PROPAGATION_REQUIRED</prop> + <prop key="update*">PROPAGATION_REQUIRED</prop> + <prop key="*">PROPAGATION_SUPPORTS</prop> + </props> + </property> + </bean> +]]></source> + </p> + <p>There are several transactional attributes that control the behavior of transactions on the wrappered bean</p> + <ul> + <li><b>proxyInterfaces</b> - the name of the interface to automatically proxy calls to. Only calls to this interface will be intercepted. + This ensures that Jetspeed services only interact with each other along the interface contract of the Jetspeed API. + </li> + <li><b>target</b> - the name of the bean being proxied for transactions. In this case its our Permission Manager implementation</li> + <li><b>transactionalAttributes</b> - attributes that can control the behavior of methods on the proxied interface. Methods are listed + as property keys and can contain wildcards such as all methods that start with <code>add*</code>. Then the body of the tag can contain + either PROPAGATION_REQUIRED or PROPAGATION_SUPPORTS keywords, as well as exception handling behavior described below. + </li> + </ul> + <p><b>Transaction Propagation Required</b> - If propagation is required, then the method is required to be a part of a transaction. If, when the method + is called, there is not an active transaction, a transaction will be immediately started by the proxy (interceptor). Methods that store to a persistent database + are usually marked as propagation required. + </p> + <p><b>Transaction Propagation Supported</b> - If propagation is only supported, then the method is NOT required to be a part of a transaction. If, when the method + is called, there is not an active transaction, a transaction will be NOT be started by the proxy (interceptor). If there is a transaction active, the + method will join the transaction. Methods not marked with either required or supported properties will not participate in transactions. + </p> + <p><b>Exception Handling and Rollback</b> - + Transactions can also be committed or rolled back based on one or more Exception classes. In the example below + we use <code>-</code>, the minus sign, to denote that any <code>RegistrationExceptions</code> that occur on any methods that start with <code>register*</code> + will cause the transaction to <strong>rollback</strong>. On the contrary, using a <code>+</code>, a plus sign, will cause the transaction + to commit for the given method and exception. + +<source><![CDATA[ + <property name="transactionAttributes"> + <props> + <prop key="register*">PROPAGATION_REQUIRED,-org.apache.jetspeed.administration.RegistrationException</prop> + </props> + </property> +]]></source> + </p> + </subsection> + <subsection name="Nesting and Joining Transactions"> + <p> Transactions can be nested when one service calls another service. Take for example, the User Registration portlet which uses + the Jetspeed Administration service method named <code>registerUser</code>. User registration requires transactional calls to + both the Permission Manager and the User Manager. The transaction begins on the Jetspeed Administration service, calls into the + Permission Manager to the grantPermission method, and then the User Manager's storeUser method. If any of these methods fails, + the entire transaction is rolled back. If all methods succeed, the transaction is committed as shown below.</p> + <p> + <img src="images/transaction-interception.jpg" border="0"/><br/><br/> + </p> + </subsection> + + </section> + </body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-user-attributes.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-user-attributes.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-user-attributes.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/guide-user-attributes.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,132 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<document> + <properties> + <title>Guide to Defining User Attributes</title> + <subtitle>PLT.17 User Information Configuration</subtitle> + <authors> + <person name="Ate Douma" email="[email protected]"/> + </authors> + </properties> + <body> + <section name="Defining User Attributes"> + <p> + The Portlet Specification defines how Portlet Applications can use User Attributes.<br/> + The attributes must be defined in the portlet.xml like (see PLT.17.1):</p> + <source><![CDATA[ +<portlet-app version="1.0" xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd";> + <user-attribute> + <description>User Given Name</description> + <name>user.name.given</name> + </user-attribute> + <user-attribute> + <description>User Last Name</description> + <name>user.name.family</name> + </user-attribute> + <user-attribute> + <description>User eMail</description> + <name>user.home-info.online.email</name> + </user-attribute> + ... +</portlet-app>]]></source> + <p> + Once attributes are defined like this, a portlet can access the current values for the logged on + user as an unmodifiable Map from the PortletRequest using the USER_INFO constant defined in the + PortletRequest interface (see PLT.17.2):</p> + <source> +Map userInfo = (Map)request.getAttribute(PortletRequest.USER_INFO); +String givenName = (userInfo!=null) ? (String)userInfo.get("user.name.given") : ""; +String lastName = (userInfo!=null) ? (String)userInfo.get("user.name.family") : ""; +String email = (userInfo!=null) ? (String)userInfo.get("user.home-info.online.email") : "";</source> + <p> + What is not defined by the Portlet Specification is <em>how</em> the Portal + must map the defined User Attributes to concrete attributes of a user.</p> + </section> + <section name="Mapping User Attributes"> + <p> + Jetspeed-2 provides a very flexible way to define concrete User attributes and defining access to them.</p> + <p> + Concrete User attributes are stored using User Preferences for which Jetspeed-2 provides its own database + back end for storage (which is customizable by the way like almost any component of Jetspeed-2). The user + attributes implementation leverages Jetspeed's + <a href="../devguide/dev-prefs.html">java.util.prefs.Preferences</a> implementation.<br/> + The concrete User attributes are stored under a specific node in the User preferences and can contain + any named attribute at will.<br/> + These concrete User attributes can be mapped to the defined User Attributes in the portlet.xml in two ways: + <ol> + <li> + Using an exact match of attribute names + </li> + <li> + Using a custom mapping definition in a jetspeed-portlet.xml + </li> + </ol> + </p> + <subsection name="Custom User Attribute Mapping"> + <p> + If you write new Portlet Applications with Jetspeed-2 as target Portal, defining User Attributes which + match the concrete User attributes in the Portal usually will be quite straightforward<br/> + But, if you have an existing Portlet Application which you want to deploy on Jetspeed-2, there might + be a mismatch between the attribute names needed by the Portlet Application and the + concrete attribute names as stored in the Jetspeed-2 User Preferences.</p> + <p> + <em> + Note: The Portlet Specification defines a set of attribute names which are recommended to be used + in Appendix PLT.D.<br/> + Portlet Applications using these attribute names and Portals storing the concrete User attributes + also using these names won't need any custom attribute mapping as will be described below.<br/> + Although Jetspeed-2 allows a fully free definition of the concrete User attributes, + it is recommended to use these predefined attributes names as much as possible.</em></p> + <p> + The jetspeed-portlet.xml allows jetspeed specific configurations and customizations to be specified.<br/> + This deployment document isn't required, but will be processed if found within the WEB-INF folder of a + Portlet Application war.<br/> + Jetspeed specific configurations must be defined using the "http://portals.apache.org/jetspeed"; namespace.</p> + <p> + User attribute mapping is defined using an "user-attribute-ref" element containing a "name" element defining + the custom user attribute name and a "name-link" element defining the concrete attribute name to which it + is mapped:</p> + <source><![CDATA[ +<portlet-app version="1.0" + xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"; + xmlns:js="http://portals.apache.org/jetspeed";> + <js:user-attribute-ref> + <js:name>user-name-given</js:name> + <js:name-link>user.name.given</js:name-link> + </js:user-attribute> + <js:user-attribute-ref> + <js:name>user-name-family</js:name> + <js:name-link>user.name.family</js:name-link> + </js:user-attribute> + ... +</portlet-app>]]></source> + <p> + Using the above custom mapping as an example, the Portlet can now access the user attributes as follows:</p> + <source> +Map userInfo = (Map)request.getAttribute(PortletRequest.USER_INFO); +String givenName = (userInfo!=null) ? (String)userInfo.get("user-name-given") : ""; +String lastName = (userInfo!=null) ? (String)userInfo.get("user-name-family") : ""; +String email = (userInfo!=null) ? (String)userInfo.get("user.home-info.online.email") : "";</source> + <p> + Note that the email attribute for which no custom mapping was defined still can be access using + exact name matching (provided the concrete attribute is defined for the logged on user).</p> + </subsection> + </section> + + </body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/index.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/index.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/index.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/index.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,66 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<document> + <properties> + <title>Jetspeed Deployment Guide</title> + <subtitle>Guide to a Jetspeed Deployment</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]" /> + <person name="Jody McAlister" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Deployment Guide"> + <p> + This guide is targeted at helping administrators and developers configure and deploy Jetspeed to application servers. While the Administrative Guide documents configuring + Jetspeed within the portal user interface, this guide documents configuring and deploying with Spring configurations and Java properties files. + </p> + + <subsection name="Deploying Jetspeed 2"> + <p> + Jetspeed can be deployed in a variety of application servers. This guide describes the deployments procedure + for <a href="guide-tomcat.html">Apache Tomcat</a> and <a href="deploying-jetspeed-to-websphere.html">IBM Websphere</a>. + </p> + </subsection> + + <subsection name="Configuring Jetspeed 2 Components"> + <p>Jetspeed provides very flexible ways for specific configuration settings.</p> + <p>Jetspeed components are initially loaded from <strong><code>/WEB-INF/assembly/</code></strong> folder, while the default configuration properties are loaded from <strong><code>/WEB-INF/conf/jetspeed.properties.</code></strong></p> + <p>The initial/default configurations can be overridden through the <strong><code>/WEB-INF/assembly/override/</code></strong> folder, while overrides/additional values can be provided through the <strong><code>/WEB-INF/conf/override.properties.</code></strong></p> + <p>Another new feature is conditional Spring assembly loading. Jetspeed provides an extended BeanFactory + which checks a loaded Spring BeanDefinition for some extra meta data (defined within the Spring configuration itself) + against a predefined configuration, registering a BeanDefinition within Spring can be "prevented", effectively + filtering out certain definitions.</p> + </subsection> + + <subsection name="This guide"> + <p> + The deployment guide describes the <a href="jetspeed-properties.html">properties that can be configured</a>, + and how to <a href="override-properties.html">override the default values</a>. + </p> + <p> + There is a short introduction to managing <a href="config-spring.html">Spring configurations</a>, and how to + <a href="config-overrides.html">override</a> the default Spring configurations with your own deployment customization. + The entire Jetspeed portal is constructed with a Spring configuration. This deployment guide documents the key components + that you can override. The guide is categorized, in the menu on the left-hand-side, into describing the general subjects of <b>Security Components</b> and <b>Portal Components</b>. + </p> + </subsection> + + </section> + </body> +</document> \ No newline at end of file
