Package com.bea.netuix.application.communities

See
Description

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

Contents

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

• What are communities?
• Main data objects
• Community API access
• CommunityDefinition attributes
• CommunityMember attributes
• CommunityMembership attributes
• Community framework rendering
• Invitations
• Registration pages
• Error pages
• Community membership capabilities
• Callback classes
• Creating Communities and Community Templates
• Community Code Sample

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

CommunityDefinition

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.

CommunityMember

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.

CommunityMembership

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:

• invitations
• registration pages
• error pages
• callback classes
• membership capabilities

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:

Attribute	Type	Description
accessTrackingEnabled	boolean	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.
active	boolean	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.
CommunityCallbackClass	String	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.
description	String	A description of the community.
errorUri	String	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.
expirationDate	Date	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.
parentId	CommunityDefinitionId	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.
personalPagesEnabled	boolean	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.
properties	Collection 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.
public	boolean	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.
publicRegistrationEnabled	boolean	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.
registrationPageUri	String	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.
timeZone	TimeZone	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.
title	String	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

The CommunityMember object stores the following information:

Attribute	Type	Description
active	boolean	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.
external	boolean	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.
id	CommunityMemberId	A unique ID for the CommunityMember object, used to correlate it with CommunityMembership objects.
wlsUserId	String	The WLS user id (login ID) of the user.

CommunityMembership Attributes

The CommunityMembership object stores the following information:

Attribute	Type	Description
active	boolean	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.
capabilities	Collection 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.
communityDefinitionId	CommunityDefinitionId	The community definition the membership belongs to.
id	CommunityMembershipId	A unique ID for the CommunityMembership object.
joinDate	Date	The date the membership was created.
lastAccessDate	Date	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.
memberId	CommunityMemberId	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:

• Is the Community public?
  • Yes: Is the Community active?
    • Yes: Render the Community.
    • No: Redirect to the error page with error COMMUNITY_DEACTIVATED
  • No: Is a user logged in and do they have a membership in the Community?
    • Yes: Is their Community member record active?
      • Yes: Is their Community membership record active?
        • Yes: Is the Community active?
          • Yes: Render Community.
          • No: Redirect to the error page with error COMMUNITY_DEACTIVATED
        • No: Redirect to the error page with error MEMBERSHIP_DEACTIVATED
      • No: Redirect to the error page with error MEMBER_DEACTIVATED
    • No: Is public registration enabled?
      • Yes: Is a user logged in and do they have a Community member record?
        • Yes: Is the member record active?
          • Yes: Redirect to the registration page.
          • No: Redirect to the error page with error MEMBER_DEACTIVATED
        • No: Redirect to the registration page.
      • No: Is a user logged in and do they have an invitation to this Community?
        • Yes: Redirect to the registration page.
        • No: Redirect to the error page with error NO_PUBLIC_ACCESS

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:

• A community may wish to track all accesses to the community pages, but allow any authenticated user to access the community.
  • Example: This scenario is enabled by setting the CommunityDefinition's public flag to false, publicRegistrationEnabled to true, and accessTrackingEnabled to true, and set up a registration page which automatically creates memberships for authenticated users. Thus, when a user without an existing membership attempts to access the community they will be automatically redirected to the registration page, which will automatically create a membership record for them, and the portal framework will automatically track their access to the community in the membership object. The registration page could even be set up to automatically redirect to the community after creating the membership- in this case, the user would not even need to know that they had been redirected to the registration page.
• A community may wish to collect additional information from users before a membership is created.
  • Example: A community for photography enthusiasts may collect information on what type of camera the user has when creating a membership. By having all memberships in the community created through a registration page that collects this information, the community application can guarantee that this information exists for every member of the community.
• A community may wish to have existing members approve new memberships before they are created.
  • Example: The registration page could be set up to collect information from users interested in joining the community. In a workflow process, existing community members could review this information before giving approval to the user in the form of an invitation to join the community. When the user returns to the registration page with the invitation, the registration page can automatically create a membership for the user. Note for this example that the CommunityDefinition's publicRegistrationEnabled flag could be set to true to allow users without memberships attempting to access the community to be redirected to the registration page so that they could apply for membership, even though they would need to be approved before the membership is actually created.
• A community may wish to have users indicate approval of terms and conditions before users are allowed to join as members.
  • Example: The registration page could be set up to display terms and conditions to the user before it creates their membership.

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:

• CommunityContext is useful to get information about the community being registered for. It also contains methods to:
  • determine if the user already has a membership
  • create a membership in the community
  • create a membership from an invitation
  • get the CommunityInvitationContext object
• CommunityInvitationContext is useful for getting any invitations an authenticated user may have to join a community.
• CommunityRedirectionHelper is useful in determining if the user arrived at the registration page due to an automatic redirect by the portal framework or by clicking on a link in an invitation. If multiple community instances are sharing a registration page, it has a method to determine which community instance the registration page is being invoked for. CommunityRedirectionHelper also has a utility method for generating a URL to a registration page for a community, which could be displayed in a community or elsewhere.

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:

• Just after a community is created.
  • This may be useful to initialize additional data associated with a community, such as a content repository.
• Just after a community is switched from being inactive to active.
  • This may be useful to re-initialize community-associated data, send out notices to members, etc.
• Just before a community is switched from being active to inactive.
  • This may be useful to copy community-associated data, send out notices to members, etc.
• Just before a community is deleted.
  • This may be useful to copy community-associated data, send out notices to members, or remove community-associated data from a content repository.

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).

    <communities-meta>
        <title>My Community</title>
        <description>
            <value>This is a Community.</value>
        </description>
        <community-dot-file>communities/myCommunity.portal</community-dot-file>
        <callback-class>
            <locked>true</locked>
            <value>com.bea.communities.MyCommunityCallback</value>
        </callback-class>
        <expiration>
            <value>2005-03-25T22:30:00</value>
        </expiration>
        <active>
            <value>true</value>
        </active>
        <public>
            <value>true</value>
        </public>
        <personal-pages>
            <locked>true</locked>
            <value>false</value>
        </personal-pages>
        <public-registration>
            <value>true</value>
        </public-registration>
        <registration-uri>
            <locked>true</locked>
            <value>communities/myCommunity/registration.jsp</value>
        </registration-uri>
        <error-uri>
            <locked>false</locked>
            <value>communities/myCommunity/error.jsp</value>
        </error-uri>
        <access-tracking>
            <locked>false</locked>
            <value>false</value>
        </access-tracking>
        <inviter-invoker-class>
            <locked>true</locked>
            <value>com.bea.communities.myCommunity.MyInviterInvoker</value>
        </inviter-invoker-class>
    </communities-meta>

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.