com.bea.netuix.servlets.manager.communities
Class CommunityContext

java.lang.Object
  com.bea.netuix.servlets.manager.communities.CommunityContext

public final class CommunityContext
extends Object

The CommunityContext object serves as a cache container and accessor for community and membership information for a HttpSession. Each CommunityContext object instance has exactly one community in scope, in the form of a CommunityDefinition object. If the authenticated principal (logged-in user) for the HttpRequest has a membership in the community, the CommunityContext also contains the membership information in the form of a CommunityMembership object.

CommunityContexts can be accessed for the "default" community (the one associated with the Desktop currently being viewed, if any) but may also be retrieved for any CommunityDefinition within the webapp.

The caching scope used within a CommunityContext is controlled by the underlying CommunityUserContext object. There are cases where the cache can become stale; these are discussed along with remedies in the documentation for CommunityUserContext.

The overview of community functionality contains a description of the community framework.

See Also

CommunityUserContext, CommunityInvitationContext, CommunityRedirectionHelper, CommunityInvitationHelper, ICommunityManager, ICommunityMemberManager

Method Summary

void	activateCommunity(Date expirationDate) Sets the state of the community associated with this CommunityContext to ACTIVE for the specified time.
void	activateMembership() Activates the CommunityMembership associated with this CommunityContext.
void	addMembershipCapability(MembershipCapability capability) Adds a capability to the CommunityMembership associated with this CommunityContext.
void	checkPermissions(javax.servlet.http.HttpServletResponse response, boolean updateAccess) Checks to see if the currently-logged-in (or not logged-in) individual is allowed to access the community in this CommunityContext, and if so, automatically updates the membership's last access date if appropriate.
protected Object	clone() Throws CloneNotSupportedException, as cloning of CommunityContext objects is not allowed.
CommunityMembership	createMembership() Creates a CommunityMembership for the authenticated principal in the current Request object for the community associated with this CommunityContext.
CommunityMembership	createMembership(Invitation invitation) Creates a CommunityMembership for the authenticated principal in the current Request object for the specified Invitation.
void	deactivateCommunity() Sets the state of the community associated with this CommunityContext to INACTIVE.
void	disableMembership() Disables the CommunityMembership associated with this CommunityContext.
void	disablePersonalPages() Disables members from adding personal pages to the community associated with this CommunityContext.
void	enablePersonalPages() Enables members to add personal pages to the community associated with this CommunityContext.
boolean	equals(Object o)
CommunityDefinition	getCommunity() Retrieves the CommunityDefinition for the community associated with this CommunityContext.
static CommunityContext	getCommunityContext(javax.servlet.http.HttpServletRequest request) A convenience method for returning the "default" CommunityContext object associated with the specified Request.
static CommunityContext	getCommunityContext(javax.servlet.http.HttpServletRequest request, CommunityDefinition community) Returns the CommunityContext object associated with the specified request and CommunityDefinition.
static CommunityContext	getCommunityContext(javax.servlet.http.HttpServletRequest request, CommunityDefinitionId communityId) Returns the CommunityContext object associated with the specified request and CommunityDefinitionId.
static CommunityContext	getCommunityContext(javax.servlet.http.HttpServletRequest request, CommunityMembership membership) Returns the CommunityContext object associated with the specified request and CommunityMembership for the currently authenticated principal.
static CommunityContext	getCommunityContext(javax.servlet.http.HttpServletRequest request, CommunityURI communityUri) Returns the CommunityContext object associated with the specified request and community.
CommunityInvitationContext	getCommunityInvitationContext() Returns the CommunityInvitationContext object for this community.
CommunityMembershipCriteria	getCommunityMembershipCriteria() Returns a CommunityMembershipCriteria object for the community represented by this CommunityContext.
static GenericURL	getCommunityURL(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, CommunityURI community) Returns a URL to the specified community, if the URL can be determined.
CommunityUserContext	getCommunityUserContext() Returns the CommunityUserContext object backing this CommunityContext.
CommunityMembership	getMembership() Retrieves the CommunityMembership object assicated with this CommunityContext object, if a membership exists.
int	hashCode()
boolean	isCommunityInAdminMode()
boolean	isMembershipActive() Determines if the member and membership records associated with the authenticated principal (logged-in user) and this CommunityContext object are active or disabled.
void	removeMembership() Destroys the CommunityMembership associated with this CommunityContext.
void	removeMembershipCapability(MembershipCapability capability) Removes a capability from the CommunityMembership associated with this CommunityContext.
void	setCommunityExpirationDate(Date expirationDate) Sets the expiration date for the community associated with this CommunityContext.
String	toString()
CommunityDefinition	updateCommunity(CommunityDefinition communityDefinition) Deprecated This method does not invoke CommunityCallback classes registered with the community if the community is activated or deactivated through this call. Use updateCommunity(com.bea.netuix.application.definition.CommunityDefinition, boolean) instead.
CommunityDefinition	updateCommunity(CommunityDefinition communityDefinition, boolean invokeCallbackClass) Updates the CommunityDefinition for the community associated with this CommunityContext.
long	updateLastAccessDate() Updates the last access date for the membership associated with this CommunityContext to the current time.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

getCommunityContext

public static CommunityContext getCommunityContext(javax.servlet.http.HttpServletRequest request)

A convenience method for returning the "default" CommunityContext object associated with the specified Request. This is the CommunityContext appropriate for the Desktop viewed by the Request. This method should be called every time a CommunityContext is needed, and the returned value should never be cached or kept as a reference, since the context object maintains a reference to the request and will be invalid on subsequent requests. This method is optimized internally to only create a new context object once per request, so there is no performance benefit to maintaing references to the return value in any case.

Parameters

request - the HttpServletRequest.

Returns

the "default" (desktop-associated) CommunityContext object associated with the request, or null if the desktop associated with the request is not a community desktop.

getCommunityContext

public static CommunityContext getCommunityContext(javax.servlet.http.HttpServletRequest request,
                                                   CommunityURI communityUri)

Returns the CommunityContext object associated with the specified request and community. This method should be called every time a CommunityContext is needed, and the returned value should never be cached or kept as a reference, since the context object maintains a reference to the request and will be invalid on subsequent requests. This method is optimized internally to only create a new context object once per request, so there is no performance benefit to maintaing references to the return value in any case.

Parameters

request - the HttpServletRequest.

communityUri - the URI for the community.

Returns

the appropriate CommunityContext object, or null if no community with the specified URI exists.

getCommunityContext

public static CommunityContext getCommunityContext(javax.servlet.http.HttpServletRequest request,
                                                   CommunityDefinition community)

Returns the CommunityContext object associated with the specified request and CommunityDefinition. This may be useful for obtaining a CommunityContext if the CommunityDefinition has already been retrieved through a call from a method returning only CommunityDefintion objects, such as the CommunityUserContext.getCommunities() method. This method should be called every time a CommunityContext is needed, and the returned value should never be cached or kept as a reference, since the context object maintains a reference to the request and will be invalid on subsequent requests. This method is optimized internally to only create a new context object once per request, so there is no performance benefit to maintaing references to the return value in any case.

Parameters

request - the HttpServletRequest.

community - the community.

Returns

the appropriate CommunityContext object.

getCommunityContext

public static CommunityContext getCommunityContext(javax.servlet.http.HttpServletRequest request,
                                                   CommunityDefinitionId communityId)

Returns the CommunityContext object associated with the specified request and CommunityDefinitionId. This method should be called every time a CommunityContext is needed, and the returned value should never be cached or kept as a reference, since the context object maintains a reference to the request and will be invalid on subsequent requests. This method is optimized internally to only create a new context object once per request, so there is no performance benefit to maintaing references to the return value in any case.

Parameters

request - the HttpServletRequest.

communityId - the community ID.

Returns

the appropriate CommunityContext object.

getCommunityContext

public static CommunityContext getCommunityContext(javax.servlet.http.HttpServletRequest request,
                                                   CommunityMembership membership)

Returns the CommunityContext object associated with the specified request and CommunityMembership for the currently authenticated principal. This may be useful for obtaining a CommunityContext if the CommunityMembership has already been retrieved through a call from a method returning only CommunityMembership objects, such as the CommunityUserContext.getCommunityMembership() method. CommunityContext objects can only be obtained for the currently authenticated principal (user) or, if no authenticated principal exists for the request, the anonymous user. Since the anonymous user cannot have a membership in a community, this method will only return a CommunityContext if the specified membership is for the currently authenticated principal in the request. This method should be called every time a CommunityContext is needed, and the returned value should never be cached or kept as a reference, since the context object maintains a reference to the request and will be invalid on subsequent requests. This method is optimized internally to only create a new context object once per request, so there is no performance benefit to maintaing references to the return value in any case.

Parameters

request - the HttpServletRequest.

membership - the membership to obtain the CommunityContext for. This membership must be for the authenticated principal in the request; if the membership is for any other user, this methos will return null.

Returns

the appropriate CommunityContext object, or null if no appropriate CommunityContext exists.

getCommunityURL

public static GenericURL getCommunityURL(javax.servlet.http.HttpServletRequest request,
                                         javax.servlet.http.HttpServletResponse response,
                                         CommunityURI community)

Returns a URL to the specified community, if the URL can be determined. If the specified community is in another web application which is not deployed on this server and the URL to the webapp cannot be determined, null will be returned.

Parameters

request - the request object.

response - the response object.

community - the community to get a URL to.

Returns

a URL to the specified community, if the URL can be determined. If the specified community is in another web application which is not deployed on this server and the URL to the webapp cannot be determined, null will be returned.

getCommunityUserContext

public CommunityUserContext getCommunityUserContext()

Returns the CommunityUserContext object backing this CommunityContext.

Returns

the CommunityUserContext object backing this CommunityContext.

checkPermissions

public void checkPermissions(javax.servlet.http.HttpServletResponse response,
                             boolean updateAccess)
                      throws CommunityAccessRedirectionException

Checks to see if the currently-logged-in (or not logged-in) individual is allowed to access the community in this CommunityContext, and if so, automatically updates the membership's last access date if appropriate. This method is automatically called by the framework for the "default" community (associated with the currently-viewed desktop) and does not need to be called in this case. When accessing community information outside of a community desktop (or accesssing information for a different community) this method should be called by the application to determine if the user has rights to access the community information.

This method throws a CommunityAccessRedirectionException if the authenticated principal (or lack thereof) is not allowed to view the community associated with this CommunityContext. The exception contains information on what access violation occured and where the user can be redirected to to see the community error page or the community registration page. For portlets using community information outside of the community desktop, this information can be used to display "access denied" type error messages or offer a link to the community registration page without actually affecting a redirect.

Note that this method may not throw an exception even if the member or membership is disabled, if the community is public. Therefore, the isMembershipActive() method can be used to ensure the membership and member records are not disabled.

If the user has permission to view the community, and the community has access tracking enabled, the membership's last access date is updated if it is the first attempt at access for this community in this HttpSession and the updateAccess argument is true. In some cases, access rights may need to be ascertained without the application qualifying it as a full "access" to the community; this parameter allows control over this feature. Note that the updateLastAccessDate() method may be used to force updating at any time.

The logic implemented by this method is:

• Is the Community public?
  • Yes: Is the Community active?
    • Yes: update membership's last access date if appropriate and return.
    • No: throw an exception to 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: update membership's last access date if appropriate and return.
          • No: throw an exception to redirect to the error page with error COMMUNITY_DEACTIVATED
        • No: throw an exception to redirect to the error page with error MEMBERSHIP_DEACTIVATED
      • No: throw an exception to 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: throw an exception to redirect to the registration page.
          • No: throw an exception to redirect to the error page with error MEMBER_DEACTIVATED
        • No: throw an exception to redirect to the registration page.
      • No: Is a user logged in and do they have an invitation to this Community?
        • Yes: throw an exception to redirect to the registration page.
        • No: throw an exception to redirect to the error page with error NO_PUBLIC_ACCESS

Parameters

response - the response object.

updateAccess - indicates whether or not the last access date for the membership should be updated to reflect this access. See method description for a full discussion of this.

Throws

CommunityAccessRedirectionException - if the authenticated principal (or lack thereof) is not allowed to view the currently viewed community. The exception contains information on what access violation occured and where the user can be redirected to to see an explanitory error page or the community registration page.

See Also

isMembershipActive()

isMembershipActive

public boolean isMembershipActive()

Determines if the member and membership records associated with the authenticated principal (logged-in user) and this CommunityContext object are active or disabled. Note that it is possible to have an active membership and member record but to also have the community disabled; for this reason this method is not equivalent to the checkPermissions() method.

Returns

true if both the CommunityMember and CommunityMembership associated with this CommunityContext are active; false if the member or membership record does not exist or are disabled.

See Also

checkPermissions(javax.servlet.http.HttpServletResponse, boolean)

getCommunityInvitationContext

public CommunityInvitationContext getCommunityInvitationContext()

Returns the CommunityInvitationContext object for this community.

getCommunity

public CommunityDefinition getCommunity()

Retrieves the CommunityDefinition for the community associated with this CommunityContext. This method returns a new clone of the CommunityDefinition.

Returns

the CommunityDefinition object for the community associated with this CommunityContext

getMembership

public CommunityMembership getMembership()

Retrieves the CommunityMembership object assicated with this CommunityContext object, if a membership exists.

Returns

the CommunityMembership object for the currently-logged-in user for the community associated with this CommunityContext object, or null if no such membership exists.

isCommunityInAdminMode

public boolean isCommunityInAdminMode()

updateCommunity

@Deprecated
public CommunityDefinition updateCommunity(CommunityDefinition communityDefinition)
                                    throws ObjectNotFoundException,
                                           NotEntitledException,
                                           IllegalOperationException,
                                           ObjectInUseException,
                                           RemoteException

Deprecated This method does not invoke CommunityCallback classes registered with the community if the community is activated or deactivated through this call. Use updateCommunity(com.bea.netuix.application.definition.CommunityDefinition, boolean) instead.

Updates the CommunityDefinition for the community associated with this CommunityContext.

Parameters

communityDefinition - community definition with updated attributes

Returns

The updated CommunityDefinition

Throws

ObjectNotFoundException - if community to be updated does not exist

NotEntitledException - if current user does not have permission to update this community

IllegalOperationException - if part of or all of the update is illegal based on the current state of the community for e.g. if the update tries to set expirationDate on or activate a community that is marked as a template

ObjectInUseException - if the update tries to point the community to a desktop that is already in use by another community

RemoteException

updateCommunity

public CommunityDefinition updateCommunity(CommunityDefinition communityDefinition,
                                           boolean invokeCallbackClass)
                                    throws ObjectNotFoundException,
                                           NotEntitledException,
                                           IllegalOperationException,
                                           ObjectInUseException,
                                           RemoteException,
                                           CommunityCallbackException

Updates the CommunityDefinition for the community associated with this CommunityContext.

Parameters

communityDefinition - community definition with updated attributes

invokeCallbackClass - if true and the community is activated or deactivated by this call, invokes the appropriate methods on the CommunityCallback object associated with the community, if one exists. If false, no callback call is made.

Returns

The updated CommunityDefinition

Throws

ObjectNotFoundException - if community to be updated does not exist

NotEntitledException - if current user does not have permission to update this community

IllegalOperationException - if part of or all of the update is illegal based on the current state of the community for e.g. if the update tries to set expirationDate on or activate a community that is marked as a template

ObjectInUseException - if the update tries to point the community to a desktop that is already in use by another community

CommunityCallbackException - if a callback class registered with the community is invoked and throws an exception

RemoteException

activateCommunity

public void activateCommunity(Date expirationDate)
                       throws ObjectNotFoundException,
                              NotEntitledException,
                              IllegalOperationException,
                              IllegalArgumentException,
                              CommunityCallbackException,
                              RemoteException

Sets the state of the community associated with this CommunityContext to ACTIVE for the specified time. A community in the ACTIVE state can accept new members, supports updates and addition of new content.

Parameters

expirationDate - The new expiration date for the community, or null if the community should not expire.

Throws

ObjectNotFoundException - if community to be activated does not exist

NotEntitledException - if current user does not have permission to activate this community

IllegalOperationException - if this community is a template

IllegalArgumentException - if the supplied expirationDate is in the past

CommunityCallbackException - if an error occurs when making a community callback

RemoteException

deactivateCommunity

public void deactivateCommunity()
                         throws IllegalArgumentException,
                                ObjectNotFoundException,
                                NotEntitledException,
                                CommunityCallbackException,
                                RemoteException

Sets the state of the community associated with this CommunityContext to INACTIVE. A community in the INACTIVE state does not support any interaction excepting that with certain priviledged users.

Throws

ObjectNotFoundException - if community to be deactivated does not exist

NotEntitledException - if current user does not have permission to deactivate this community

CommunityCallbackException - if an error occurs when making a community callback

RemoteException

IllegalArgumentException

setCommunityExpirationDate

public void setCommunityExpirationDate(Date expirationDate)
                                throws IllegalArgumentException,
                                       ObjectNotFoundException,
                                       NotEntitledException,
                                       IllegalOperationException,
                                       RemoteException

Sets the expiration date for the community associated with this CommunityContext. The community is put into the INACTIVE state once this date has passed. Setting a new expiration date on a community resets the original expiration date and the community stays active until the new expiration date.

Parameters

expirationDate - The new expiration date.

Throws

IllegalArgumentException - If the expirationDate is before current date

ObjectNotFoundException - if specified community does not exist

NotEntitledException - if current user does not have permission to set the expirationDate for this community

IllegalOperationException - if this community is a template

RemoteException

enablePersonalPages

public void enablePersonalPages()
                         throws ObjectNotFoundException,
                                NotEntitledException,
                                RemoteException

Enables members to add personal pages to the community associated with this CommunityContext.

Throws

ObjectNotFoundException - if specified community does not exist

NotEntitledException - if current user does not have permission to perform this operation

RemoteException

disablePersonalPages

public void disablePersonalPages()
                          throws ObjectNotFoundException,
                                 NotEntitledException,
                                 RemoteException

Disables members from adding personal pages to the community associated with this CommunityContext.

Throws

ObjectNotFoundException - if specified community does not exist

NotEntitledException - if current user does not have permission to perform this operation

RemoteException

createMembership

public CommunityMembership createMembership()
                                     throws RemoteException,
                                            NotEntitledException,
                                            DuplicateObjectException

Creates a CommunityMembership for the authenticated principal in the current Request object for the community associated with this CommunityContext. Invitations may contain information about community capabilities to grant to the new membership, so when an invitation exists, the other form of this method (which takes an Invitation object) should be used. If a community member record does not exist, it is created with default values active=true and external=false. If no user is logged in, a NotEntitledException is thrown.

Returns

a CommunityMembership object containing membership information.

Throws

RemoteException

NotEntitledException - if there is no user logged in.

DuplicateObjectException - if a membership already exists for the specified member and community.

createMembership

public CommunityMembership createMembership(Invitation invitation)
                                     throws IllegalArgumentException,
                                            RemoteException,
                                            NotEntitledException,
                                            DuplicateObjectException

Creates a CommunityMembership for the authenticated principal in the current Request object for the specified Invitation. If a community member record does not exist for the currently authenticated user, one is created with default values active=true and external=false. If no user is logged in, a NotEntitledException is thrown. Note that the invitation specified may be for a community other than the community associated with this CommunityContext; in that case a membership will be created in the correct community but will not be reflected in this CommunityContext.

Returns

a CommunityMembership object containing membership information.

Throws

IllegalArgumentException - if the invitation does not have "sent" status or if the invitation is not for the currently logged-in user.

RemoteException

NotEntitledException - if there is no user logged in.

DuplicateObjectException - if a membership already exists for the specified member and community.

removeMembership

public void removeMembership()
                      throws RemoteException,
                             ObjectNotFoundException

Destroys the CommunityMembership associated with this CommunityContext.

Throws

RemoteException

ObjectNotFoundException - if there is no CommunityMembership associated with this community.

disableMembership

public void disableMembership()
                       throws RemoteException,
                              ObjectNotFoundException

Disables the CommunityMembership associated with this CommunityContext.

Throws

RemoteException

ObjectNotFoundException - if no membership exists for this CommunityContext.

activateMembership

public void activateMembership()
                        throws RemoteException,
                               ObjectNotFoundException

Activates the CommunityMembership associated with this CommunityContext.

Throws

RemoteException

ObjectNotFoundException - if there is no CommunityMembership associated with this community.

updateLastAccessDate

public long updateLastAccessDate()
                          throws ObjectNotFoundException,
                                 RemoteException

Updates the last access date for the membership associated with this CommunityContext to the current time.

Returns

the new last access timestamp for the membership.

Throws

ObjectNotFoundException - if no membership is associated with this CommunityContext object or if no user is currently logged in.

RemoteException

addMembershipCapability

public void addMembershipCapability(MembershipCapability capability)
                             throws RemoteException,
                                    ObjectNotFoundException,
                                    IllegalArgumentException

Adds a capability to the CommunityMembership associated with this CommunityContext.

Parameters

capability - the capability to add to the membership

Throws

RemoteException

ObjectNotFoundException - if there is no CommunityMembership associated with this CommunityContext

IllegalArgumentException - if the capability specified is not valid.

removeMembershipCapability

public void removeMembershipCapability(MembershipCapability capability)
                                throws RemoteException,
                                       ObjectNotFoundException,
                                       IllegalArgumentException

Removes a capability from the CommunityMembership associated with this CommunityContext.

Parameters

capability - the capability to remove from the membership

Throws

RemoteException

ObjectNotFoundException - if there is no CommunityMembership associated with this CommunityContext

IllegalArgumentException - if the capability specified is not valid.

getCommunityMembershipCriteria

public CommunityMembershipCriteria getCommunityMembershipCriteria()

Returns a CommunityMembershipCriteria object for the community represented by this CommunityContext. This object may then be used with the CommunityUserContext.getCommunityMemberships() method to retrieve the memberships for this community.

Returns

a CommunityMembershipCriteria object for the community represented by this CommunityContext.

See Also

CommunityMembershipCriteria, CommunityUserContext.getCommunityMemberships(CommunityMembershipCriteria,int)

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

clone

protected final Object clone()
                      throws CloneNotSupportedException

Throws CloneNotSupportedException, as cloning of CommunityContext objects is not allowed.

Overrides:

clone in class Object

Throws

CloneNotSupportedException