-
Notifications
You must be signed in to change notification settings - Fork 0
Use Case Description: Retrieve A Single Article (Updated)
The simplest use case, at least initially; marked as "(Updated)" since we use the new Result
-based, no-side-effects convention for use cases.
A User, whether a Member or a Guest, wishes to view a Published Article.
In future, unpublished ("Draft") Articles should be viewable by their Author separately from the editing process.
In future, a feature may exist whereby Authors permit specific other Members or groups of Members to view and Propose Contributions to unpublished Articles as though they had been Published normally.
No provision for either of these potential enhancements need be made at this time. However, implementation should make reasonable efforts not to preclude such future enhancements from being made later.
Following the pattern used in other recent use-case implementations, this use case is implemented as a class instance with an initialiser method (#initialize
), and a single public method, #call
.
The calling implementation code invokes the initialiser with the following collaborator objects as parameters:
-
:authoriser
: The authoriser follows existing practice, being an immutable value with two attributes/methods of its own:-
#current_user
returns the Member Name of the authenticated member or "Guest User" if no member has been authenticated in the current session; and -
#guest?
returnstrue
if the#current_user
is "Guest User";false
otherwise;
-
-
:repository
The repository must implement the#create(**params)
method from the [Standard Repository API]. The reader may note that this method does not affect the state of persistent storage; it does not mutate data within the scope from which it was called; and the object(s) returned are expected to be immutable values.
The calling implementation code invokes the #call
method to actually retrieve the content and metadata of a specific Article. To do so, it invokes the #call
method with a Hash as its only parameter. That Hash must contain one or more of the following keys, with suitable values:
-
:author_name
: The Member Name of the Article's Author; -
:title
: The complete and correct title of the Article.
Note that multiple Authors may Publish Articles with the same Title, though no single Author may Publish multiple Articles with the same Title.
A Member must previously have Registered, and this Registered Member must have previously Published an Article.
When the use case's #call
method is successfully completed, the returned Result
value object must have attributes such that
- the
:success?
method must have a value oftrue
; - the
:failure?
method must have a value offalse
; - the
:errors
attribute must be an empty Array-like instance; and - the
:article
attribute must be a valid object instance as returned from the repository's#find
method.
When the use case's #call
method is unsuccessfully completed, the returned Result
value object must have attributes such that
- the
:success?
method must have a value offalse
; - the
:failure?
method must have a value oftrue
; - the
:errors
attribute must be an Array-like instance containing one error-notification Hash value pair for each detected failure, as described under "Known Possible Failure Modes" below; and - the
:article
attribute must have the single symbolic value:not_matched
.
The only failure results supported by the #call
method's returned Result
value object involve failed attempts to retrieve a single, unique Article from the Repository. Thus, failures are limited to either no Article being found, or multiple Articles matching the specified parameters. (This should be limited to a search by Title without specifying the Author name.)
If the query of the Repository returns no Articles, then the :errors
array must include (only) the value
{ article: :not_found }
If the query of the Repository returns multiple Articles, then the :errors
array must include (only) the value
{ article: :not_unique }