org.osid.forum

Interface PostLookupSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface PostLookupSession
extends OsidSession

This session provides methods for retrieving Post objects. The Post represents a collection of replies.

This session defines views that offer differing behaviors when retrieving multiple objects.

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete set or is an error condition
• isolated forum view: All reply methods in this session operate, retrieve and pertain to posts defined explicitly in the current forum. Using an isolated view is useful for managing posts with the PostAdminSession.
• federated forum view: All post lookup methods in this session operate, retrieve and pertain to all posts defined in this forum and any other forums implicitly available in this forum through forum inheritence.

The methods useFederatedForumView() and useIsolatedForumView() behave as a radio group and one should be selected before invoking any lookup methods.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupPosts() Tests if this user can perform Post lookups.
Forum	getForum() Gets the Forum associated with this session.
Id	getForumId() Gets the Forum Id associated with this session.
Post	getPost(Id postId) Gets the Post specified by its Id.
PostList	getPosts() Gets all Posts.
PostList	getPostsByDate(DateTime from, DateTime to) Gets a PostList in the given date range inclusive.
PostList	getPostsByDateForPoster(Id resourceId, DateTime from, DateTime to) Gets a PostList by the given poster and in the given date range inclusive.
PostList	getPostsByGenusType(Type postGenusType) Gets a PostList corresponding to the given post genus Type which does not include posts of genus types derived from the specified Type.
PostList	getPostsByIds(IdList postIds) Gets a PostList corresponding to the given IdList.
PostList	getPostsByParentGenusType(Type postGenusType) Gets a PostList corresponding to the given post genus Type and include any additional posts with genus types derived from the specified Type.
PostList	getPostsByRecordType(Type postRecordType) Gets a PostList containing the given post record Type.
PostList	getPostsForPoster(Id resourceId) Gets a PostList for the given poster.
void	useComparativePostView() The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useFederatedForumView() Federates the view for methods in this session.
void	useIsolatedForumView() Isolates the view for methods in this session.
void	usePlenaryPostView() A complete view of the Post returns is desired.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getForumId

Id getForumId()

Gets the Forum Id associated with this session.

Returns:

the Forum Id associated with this session

Compliance:

mandatory - This method must be implemented.

getForum

Forum getForum()
               throws OperationFailedException,
                      PermissionDeniedException

Gets the Forum associated with this session.

Returns:

the forum

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupPosts

boolean canLookupPosts()

Tests if this user can perform Post lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not offer lookup operations to unauthorized users.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativePostView

void useComparativePostView()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.

Compliance:

mandatory - This method is must be implemented.

usePlenaryPostView

void usePlenaryPostView()

A complete view of the Post returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.

Compliance:

mandatory - This method is must be implemented.

useFederatedForumView

void useFederatedForumView()

Federates the view for methods in this session. A federated view will include posts in forums which are children of this forum in the forum hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedForumView

void useIsolatedForumView()

Isolates the view for methods in this session. An isolated view restricts retrievals to this forum only.

Compliance:

mandatory - This method is must be implemented.

getPost

Post getPost(Id postId)
             throws NotFoundException,
                    OperationFailedException,
                    PermissionDeniedException

Gets the Post specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Post may have a different Id than requested, such as the case where a duplicate Id was assigned to a Post and retained for compatibility.

Parameters:

postId - Id of the Post

Returns:

the post

Throws:

NotFoundException - postId not found

NullArgumentException - postId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getPostsByIds

PostList getPostsByIds(IdList postIds)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Gets a PostList corresponding to the given IdList. In plenary mode, the returned list contains all of the posts specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Posts may be omitted from the list and may present the elements in any order including returning a unique set.

Parameters:

postIds - the list of Ids to retrieve

Returns:

the returned Post list

Throws:

NotFoundException - an Id was not found

NullArgumentException - postIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPostsByGenusType

PostList getPostsByGenusType(Type postGenusType)
                             throws OperationFailedException,
                                    PermissionDeniedException

Gets a PostList corresponding to the given post genus Type which does not include posts of genus types derived from the specified Type. In plenary mode, the returned list contains all known posts or an error results. Otherwise, the returned list may contain only those posts that are accessible through this session.

Parameters:

postGenusType - a post genus type

Returns:

the returned Post list

Throws:

NullArgumentException - postGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPostsByParentGenusType

PostList getPostsByParentGenusType(Type postGenusType)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets a PostList corresponding to the given post genus Type and include any additional posts with genus types derived from the specified Type. In plenary mode, the returned list contains all known posts or an error results. Otherwise, the returned list may contain only those posts that are accessible through this session.

Parameters:

postGenusType - a post genus type

Returns:

the returned Post list

Throws:

NullArgumentException - postGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPostsByRecordType

PostList getPostsByRecordType(Type postRecordType)
                              throws OperationFailedException,
                                     PermissionDeniedException

Gets a PostList containing the given post record Type. In plenary mode, the returned list contains all known posts or an error results. Otherwise, the returned list may contain only those posts that are accessible through this session.

Parameters:

postRecordType - a post record type

Returns:

the returned Post list

Throws:

NullArgumentException - postRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPostsByDate

PostList getPostsByDate(DateTime from,
                      DateTime to)
                        throws OperationFailedException,
                               PermissionDeniedException

Gets a PostList in the given date range inclusive. In plenary mode, the returned list contains all known posts or an error results. Otherwise, the returned list may contain only those posts that are accessible through this session.

Parameters:

from - start of date range

to - end of date range

Returns:

the returned Post list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPostsForPoster

PostList getPostsForPoster(Id resourceId)
                           throws OperationFailedException,
                                  PermissionDeniedException

Gets a PostList for the given poster. In plenary mode, the returned list contains all known posts or an error results. Otherwise, the returned list may contain only those posts that are accessible through this session.

Parameters:

resourceId - a resource Id

Returns:

the returned Post list

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPostsByDateForPoster

PostList getPostsByDateForPoster(Id resourceId,
                               DateTime from,
                               DateTime to)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Gets a PostList by the given poster and in the given date range inclusive. In plenary mode, the returned list contains all known posts or an error results. Otherwise, the returned list may contain only those posts that are accessible through this session.

Parameters:

resourceId - a resource Id

from - start of date range

to - end of date range

Returns:

the returned Post list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - resourceId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPosts

PostList getPosts()
                  throws OperationFailedException,
                         PermissionDeniedException

Gets all Posts. In plenary mode, the returned list contains all known posts or an error results. Otherwise, the returned list may contain only those posts that are accessible through this session.

Returns:

a list of Posts

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.