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.

Basic Scenario

A User, whether a Member or a Guest, wishes to view a Published Article.

Further Considerations

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.

Input Details

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.

Initialiser

The calling implementation code invokes the initialiser with the following collaborator objects as parameters:

1. :authoriser: The authoriser follows existing practice, being an immutable value with two attributes/methods of its own:

   1. #current_user returns the Member Name of the authenticated member or "Guest User" if no member has been authenticated in the current session; and
   2. #guest? returns true if the #current_user is "Guest User"; false otherwise;

2. :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.

#call Method

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:

1. :author_name: The Member Name of the Article's Author;
2. :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.

Preconditions

A Member must previously have Registered, and this Registered Member must have previously Published an Article.

Effects of Success

When the use case's #call method is successfully completed, the returned Result value object must have attributes such that

1. the :success? method must have a value of true;
2. the :failure? method must have a value of false;
3. the :errors attribute must be an empty Array-like instance; and
4. the :article attribute must be a valid object instance as returned from the repository's #find method.

Effects of Failure

When the use case's #call method is unsuccessfully completed, the returned Result value object must have attributes such that

1. the :success? method must have a value of false;
2. the :failure? method must have a value of true;
3. 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
4. the :article attribute must have the single symbolic value :not_matched.

Known Possible Failure Modes

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

No Matching Article

If the query of the Repository returns no Articles, then the :errors array must include (only) the value

{ article: :not_found }

Multiple Matches

If the query of the Repository returns multiple Articles, then the :errors array must include (only) the value

{ article: :not_unique }