Package com.bea.netuix.application.communities


Interface Summary
CommunityCallback Defines callback methods that the WLP framework makes in response to various community lifecycle events.

Class Summary
AbstractCommunityCallback AbstractCommunityCallback - default implementation of the CommunityCallback interface that no-ops all methods.
CommunitiesConfigProperties Represents a set of properties which have been configured via communities-config.xml.
CommunityDesktop CommunityDesktop - specifies the desktop to be used to create a community.
CommunityInfo A structure to pass information to the CommunityDefinition constructor.
CommunityMember Represents a single CommunityMember.
CommunityMembership CommunityMembership - value object class that contains information about a membership of a CommuntityMember to a Community.
CommunityMembershipCriteria The CommunityMembershipCriteria object is used to specify attributes used to find specific CommunityMembership objects from a particular community.
CommunityProperty Represents a property associated with a community.
CommunityPropertyValue CommunityPropertyValue contains a value for a community property.
CommunitySearchCriteria CommunitySearchCriteria - search criteria for communities.
InvitationSearchCriteria SearchCriteria implementation used to specify a search operation to retrieve Communities Invitations.
MemberCriteria The MemberCriteria object is used to specify a member to search for.
MemberMembershipCriteria The MemberMembershipCriteria object is used to specify attributes used to find specific CommunityMembership objects for a particular user.
MembershipCapability Represents a Capability that has been granted to a CommunityMember with respect to a single CommunityMembership.
MembershipCriteria The MembershipCriteria object is used to specify attributes used to find specific CommunityMembership objects.

Package com.bea.netuix.application.communities Description

Overview of Communities Features


For quick reference, here are the main sections of this document:

What are Communities?

Communities are WebLogic Portal desktops that let users with common goals and interests create, manage, and work in their own web-based environment. Communities provide a dedicated, secure, self-managed place for work groups, partners, or other groups to collaborate and share information.

Communities provide end-user Community management and an extensible security framework, and are built on the WebLogic Portal framework. Communities leverage WebLogic Portal features, such as a dynamic and extensible rendering framework, security, federation, content management, search, personalization, and end-user customization.

Each community can be given a unique configuration which determines how it may be used by individual users. A community may be configured to have a set of members- users which have special privileges within the community. The exact privileges depend on the community's configuration and the application written on top of the community framework.

Communities Technical Details

It is necessary to understand the purpose of the three main data objects which back all community functionality before engaging in a more detailed discussion of community functionality.

Overview of Main Data Objects


Communities are implemented as special portal desktops, and are represented in the portal framework by a
CommunityDefinition object. The CommunityDefinition stores attributes about a community instance which apply to the entire community, such as whether a community requires users to be members of the community to view it. For a full discussion of community attributes, see the CommunityDefinition Attributes documentation below.


The community framework maintains a set of CommunityMember objects, which represent a link between users in WebLogic Server and the community framework. Each WLS user may have zero or one CommunityMember objects; if the user has never participated in any communities they may not have a CommunityMember object, but if they are to participate in a community as a community member, a CommunityMember object must be created for them. For a full discussion of CommunityMember attributes, see the CommunityMember Attributes documentation below.


Each community has a set of CommunityMembership objects which represent the set of users (CommunityMembers) within the community. A single user may have at most one CommunityMember object associated with them, but they may have many CommunityMembership objects- one per community in which they are a member. For a full discussion of CommunityMembership attributes, see the CommunityMembership Attributes documentation below.

Main Community Features

Besides memberships, communities have other features that distinguish them from desktops: Because communities may be configured to behave in many different ways, it is useful to understand these configuration options discussed below before continuing the discussion of these other community features.

Community API Access

For application developers, if access to an HttpServletRequest object is possible, the suggested starting point for accessing community functionality are the
CommunityUserContext and CommunityContext objects, which surface most community framework functionality and provide access to other helper classes. The CommunityUserContext serves as a cache container and accessor for community member information (community-specific user information shared across all communities) for a HttpSession and provides access to community API's out of scope of a specific CommunityContext object (methods not dealing with the currently authenticated principal, and community creation). The CommunityContext object serves as a cache container and accessor for community and membership information for a HttpSession, for a single community.

Both CommunityContext and CommunityUserContext objects may generally be obtained at the servlet level via convenience methods that use the current HttpServletRequest. Context instances obtained in this manner should never be kept via references or set into request or session attributes, as these references can end up existing across requests, and the context objects maintain an internal reference to the request they were obtained on, which can result in runtime errors. Instead, whenever one of these context objects is needed, it should be obtained directly from the current request using one of the convenience methods.

CommunityDefinition Attributes

The CommunityDefinition object determines how a community is configured within the portal framework, and has the following major configurable attributes:
accessTrackingEnabledboolean If this attribute is true, the portal framework will automatically update the lastAccess attribute of the user's CommunityMembership object when the user first accesses this community in a session, if the user is authenticated and has a membership in the community. This feature allows tracking of user visitation to communities, but is potentially expensive as the database is updated at least once per community access per session, so it is recommended that this is enabled only if it is being used.
activeboolean If false, the portal framework will not render the community but instead redirect to the error page. This attribute is automatically set to false by the community framework if the current time is after the community's expiration date, but can also be set by an application framework. In some circumstances it may be useful to temporarily or permanently disable a community to prevent user access without deleting the community entirely.
CommunityCallbackClassString The fully-qualified class name of an optional class which receives callbacks from the portal framework when the community instance is created, destroyed, activated or deactivated. The class must implement the CommunityCallback interface. For more information see the discussion of callback classes.
descriptionString A description of the community.
errorUriString A URI to an error page for this community, which is displayed if there is an error accessing the community. There are many different cases where a user may be redirected to this error page, such as if the community is deactivated or the user does not have permission to access the community; for more information see the discussion of Community Error Pages.
expirationDateDate An optional date and time when the community will automatically be deactivated by the framework. In some circumstances it may be desirable to prevent access to a community beyond a predetermined time; this is enabled by the exipirationDate feature. If set to null the framework will never automatically expire the community.
parentIdCommunityDefinitionId An optional ID of the community's "parent" community. In some circumstances, it may be useful to create communities in a hierarchical manner, so this attribute allows tracking of this relationship.
personalPagesEnabledboolean If true, users are allowed to personalize pages in the community by adding or removing portlets. If false, users are not allowed to add or remove portlets from this community's pages.
propertiesCollection of CommunityProperty A set of arbitrary properties associated with the community. The application may set and use these properties to store information about the community useful to the application framework.
publicboolean If true, any user may view the community, whether they are authenticated or not, whether they have a membership or not. If false, a user must have a membership in the community to access it. See also the publicRegistrationEnabled attribute below, as well as the framework's decision tree for rendering a community.
publicRegistrationEnabledboolean If true, any user may register for membership in the community; if false an invitation is required to join the community. See also the public attribute above, as well as the framework's decision tree for rendering a community.
registrationPageUriString A URI to the community registration page, which allows users to register for membership in the community. Users are automatically redirected to this page in certain circumstances by the portal framework. For more information see the discussion of registration pages.
timeZoneTimeZone A time zone associated with the community. The portal framework does not use this time zone in any manner, but it may be useful to applications written on the community framework to allow different communities to be localized to a specific time zone.
titleString A localizable title for the community.
There are other attributes associated with communities in the CommunityDefinition object; this is just a list of the main attributes which apply to this overview of community functionality.

CommunityMember Attributes

CommunityMember object stores the following information:
activeboolean If false, this user is prevented from participating in any community as a community member. This flag is intended for use to lock certain users out of all community functionality, for example if they have abused their privelges in the past.
externalboolean This flag is not used internally by the communities framework, but is intended for possible use by community application implementations. The flag was conceived as a mechanism for storing whether the user was added to the system as a result of receiving an invitation or existed in the system previously. However, as this flag is not used internally be the communities or portal framework, applications may use it as they see fit.
idCommunityMemberId A unique ID for the CommunityMember object, used to correlate it with CommunityMembership objects.
wlsUserIdString The WLS user id (login ID) of the user.

CommunityMembership Attributes

CommunityMembership object stores the following information:
activeboolean If false, this user is prevented from participating in the community this membership belongs to. This flag is intended for use to lock certain users out of community functionality for a particular community, for example if they have abused their privelges in the past.
capabilitiesCollection of MembershipCapability A set of capabilities the user has within the community to which this membership object belongs. These capabilities can be defined and used by the application code to allow different levels of user access to a community. See the discussion of community capabilities for more information.
communityDefinitionIdCommunityDefinitionId The community definition the membership belongs to.
idCommunityMembershipId A unique ID for the CommunityMembership object.
joinDateDate The date the membership was created.
lastAccessDateDate The date this user last accessed this community; this is tracked only if the CommunityDefinition's accessTrackingEnabled flag is true, and is updated automatically by the portal framework only the first time a user accesses a community within a session.
memberIdCommunityMemberId The ID of the CommunityMember object representing the user for this CommunityMembership.

Community Framework Rendering

When a community desktop is accessed, the portal framework examines the community's configuration and the status of the user to determine what to render. The decision tree is described here:

The portal framework invokes this logic by calling the CommunityContext.checkPermissions(javax.servlet.http.HttpServletResponse, boolean) method for the community in scope. This method may be useful for community application code in some circumstances as well.

Community Invitations

Invitations are messages sent to users to invite them to join a community. Any community may have invitations, but they are necessary for communities which are not public and have public registration disabled-- the only way a user can join such a community is to receive an invitation.

Invitations may be sent out over any messaging system, such as email, instant messenger, portal framework notifications, or any other messaging system by implementing a provided SPI. Email-based and notification-based implementations of this SPI are provided.

When a user receives an invitation, they can go to the community registration page and register to get a membership in the community. Invitations may contain a set of membership capabilities, so that when the user redeems the invitation for a membership they are automatically given the capabilities included in the invitation.

For an in-depth discussion of invitations, see the com.bea.netuix.application.communities.invitations package.

Community Registration Page

Each community may have an associated registration page, which allows the community to customize how users obtain memberships. For example, registration pages could be set up to support the following use cases: There are many other possible use cases; the registration page mechanism was used to give applications maximum flexibility in controlling creation of community memberships.

Registration pages may be implemented using any technology; for example it could be a simple JSP, a single portlet or mutiple portlets within a portal. Unless the CommunityDefinition's public attribute is set to true, the registration page cannot be part of the community desktop, as the portal framework will not allow users without memberships in the community to view any part of the community desktop.

Multiple community instances may share a single registration page.

Several utility classes exist which make implementing registration page functionality easier. For additional information, see the following objects:

A descriptive and feature-rich sample registration page implementation can be found in the community sample.

Community Error Page

Each community has an associated error page to which users are automatically redirected in certain circumstances by the portal framework. Multiple community instances may share a single error page. The CommunityRedirectionHelper class can help to determine which community instance the error page is being rendered for and why the error page is being rendered.

If the community's public and publicRegistrationEnabled attributes are set to false, an unauthenticated user attempting to access the community will be automatically redriected to the error page, so it may be useful to offer login functionality on the error page.

Error pages may be implemented using any technology; for example it could be a simple JSP, a single portlet or a portal.

A descriptive and feature-rich sample error page implementation can be found in the community sample.

Community Membership Capabilities

To enable users to act in different roles in individual communities, each community membership may be assigned a set of membership capabilities. These capabilities can be used by the community application to determine what a user can do within a community. The complete set of membership capabilities available for a community application's use are definable at the enterprise application level in the META-INF/communities-config.xml file.

Example: In a discussion community, a Moderator capabality could be defined such that only users with the Moderator capabality in the community can approve or delete other members' submissions.

Membership capabilities are represented in the community framework by the MembershipCapability object. This object also gives access to the complete set of membership capabilities configured for an enterprise application. Each CommunityMembership object stores the set of all capabilities a membership has been granted.

The CapabilityRoleBootstrapper class can be used at application deployment or configuration time to create default membership capability based role policies. These allow community applications to perform standard isUserInRole calls to determine if a user has a particular capability in the community in scope. They are set up as expression-based roles that use the current user's CommunityContext to determine capabilities, and cause the role evaluation to map to whether or not that user has the specified capability in the current community.

When invitations are created, a set of membership capabilities can be added to the invitation so that when the user creates a membership from the invitation they automatically are given the capabilities.

Community Callback Classes

Communities can have a callback class associated with them which is invoked by the portal framework: The callback class is set on the CommunityDefinition and must implement the CommunityCallback interface.

Creating Communities and Community Templates

Communities may be created in a number of ways, both from the Portal Admin Tools or via programmatic means. Additionally, the Communities Framework supports mechanisms for assembling development time information necessary to create communities as well as means for creating templates from which actual Community Desktop instances can be created.

Programmatic creation of Communities is done via the CommunityManager EJB persistence manager. Contained within this manager are methods to create Communities using only a reference to a .portal file plus other required information in a CommunitiesInfo object, methods to create Communities based off of other existing Community Desktops, methods to create Community Templates, and methods to create Communities based off of an existing Community Template.

Community Templates are generally created, managed and accessed via the Portal Admin Tools, and may be part of either the Library or within individual Portals. Library Templates may be instantiated into Community Desktops anywhere within the enterprise application, while Templates within Portals are restricted to being instantiated within just that Portal.

Templates are useful for use cases where there is an archetypical type of Community that is expected to be created more than once, either by a Portal Admin or, via the Community Visitor Tools, by non-admin end users that are entitled to create Communities on their own. Communities created from a Template are identical to the Template Community Desktop except for desktop path (and portal path in the case of Library Templates), as well as anything else that is overriden on instantiation of the Community Desktop.

Using the Portal Admin tools, it is possible to create either a Community Template or a CommunityDesktop directly by specifying all of the required details for that type of resource. Since this typically involves a lot of information that may not originate with the Portal Administrator creating the Communities or Templates, developers have the option of creating .ctmeta files which can be used by the Portal Admin Tools to prepopulate the form fields on the Community Desktop and Template creation pages. This file type is ONLY used in the Portal Admin Tools, and is not something that can be read via the programmatic manager. Use of a .ctmeta file is not strictly required, but is highly recommended as manual input of all of the required information to create a Community Desktop or Template is complex and error prone.

Below is an example of a .ctmeta file. This is an XML file format that is based off of the netuix-communities-meta-1_0_0.xsd schema (netuix_schema.jar, /schema/netuix-communities-meta-1_0_0.xsd).

        <title>My Community</title>
            <value>This is a Community.</value>

Community Sample

A sample of community application code including sample error and registration page implementations is available on Oracle's Dev2dev website. Performing a web search for "dev2dev community sample" should locate this sample.

Copyright © 2011, Oracle. All rights reserved.