uk.ac.sheffield.vtts.client.pojo

Class DocumentStore

java.lang.Object

uk.ac.sheffield.vtts.client.pojo.DocumentStore

public class DocumentStore
extends java.lang.Object

DocumentStore is a correct POJO implementation of the DocumentStore.xml specification. This uses the State Pattern (a Design Pattern from Gamma, et al.) for its implementation. All requests are delegated to an abstract State, which has concrete subclasses LoggedOut and LoggedIn, which respond to certain requests and ignore others. This is a good implementation strategy to ensure that no information is returned by a service, when it is in an inappropriate state.

Otherwise, the DocumentStore consists of a Map from customers to their own private storage space; the space consists of indexed Document sets, where each index maps to a List of versions of the Document. Each customer has previously registered and is given an SLA specifying a storage allocation, in terabytes, and an encryption standard. This example uses a witness-type for the Document, and also demonstrates how a service may throw exceptions. This service defines two kinds of RuntimeException, which mimic "Not Found" kinds of http error. These are thrown under suitable conditions, such that the test-driver must expect these exceptions during testing.

Suggestions are given for how to modify the source code to seed faults deliberately, which will be detected during testing.

Version:

1.0

Author:

Anthony J H Simons

Constructor Summary

Constructors

Constructor and Description
DocumentStore() Creates this DocumentStore.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.Integer	deleteVersion(java.lang.Integer docid, java.lang.Integer version) If LoggedIn, attempts to delete a Document with the given docid and version number.
Document	getDocument(java.lang.Integer docid) If LoggedIn, attempts to retrieve a Document with the given docid.
java.lang.Integer	getEncryption() If LoggedIn, enacts getEncryption/ok and returns the encryption standard for the customer.
java.lang.String	getScenario() Returns the last scenario that was enacted.
java.lang.String	getState() Returns the last state that was entered.
java.lang.Integer	getStorageLimit() If LoggedIn, enacts getStorageLimit/ok and returns the allocated storage for the customer.
java.lang.Integer	getStorageUsed() If LoggedIn, enacts getStorageUsed/ok and returns the storage used by the customer.
Document	getVersion(java.lang.Integer docid, java.lang.Integer version) If LoggedIn, attempts to retrieve a Document with the given docid and version number.
java.lang.Object[]	login(java.lang.String username, java.lang.String password) If LoggedOut, attempts to login with the given credentials.
void	logout() If LoggedIn, enacts logout/ok, clears the current customer's cached information and enters the LoggedOut state.
java.lang.Object[]	putDocument(java.lang.Integer docid, Document document) If LoggedIn, attempts to store a Document against the given docid.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DocumentStore

public DocumentStore()

Creates this DocumentStore. Resets this DocumentStore so that every customer has a full storage allocation. Enacts create/ok and enters the LoggedOut state.

Method Detail

getScenario

public java.lang.String getScenario()

Returns the last scenario that was enacted. This State Pattern implementation logs separately the request received and the response triggered (which is state-dependent). The name of the last scenario that was enacted is obtained by concatenating the request, "/" and the response.

Returns:

the last scenario that was enacted.

getState

public java.lang.String getState()

Returns the last state that was entered. This State Pattern implementation models the states explicitly as nested inner classes, which also have access to the DocumentStore's fields. The name of the current state is obtained by reflection on the class name.

Returns:

the name of the current State instance.

login

public java.lang.Object[] login(java.lang.String username,
                       java.lang.String password)

If LoggedOut, attempts to login with the given credentials. Either enacts login/ok, enters the LoggedIn state, and returns the user's maximum storage allocation and encryption standard; or enacts login/error and remains in the LoggedOut state. Otherwise, enacts login/ignore.

Parameters:

username - the username of a customer.

password - the password of this user.

Returns:

an array with the storage allocation and encryption standard, or a pair of nulls.

logout

public void logout()

If LoggedIn, enacts logout/ok, clears the current customer's cached information and enters the LoggedOut state. Otherwise, enacts login/ignore.

getEncryption

public java.lang.Integer getEncryption()

If LoggedIn, enacts getEncryption/ok and returns the encryption standard for the customer. Otherwise enacts getEncryption/ignore.

Returns:

the encryption standard, or null.

getStorageLimit

public java.lang.Integer getStorageLimit()

If LoggedIn, enacts getStorageLimit/ok and returns the allocated storage for the customer. Otherwise enacts getStorageLimit/ignore.

Returns:

the maximum storage allocated, or null.

getStorageUsed

public java.lang.Integer getStorageUsed()

If LoggedIn, enacts getStorageUsed/ok and returns the storage used by the customer. Otherwise enacts getStorageUsed/ignore.

Returns:

the storage currently used, or null.

putDocument

public java.lang.Object[] putDocument(java.lang.Integer docid,
                             Document document)
                               throws BadDocumentIdentifier

If LoggedIn, attempts to store a Document against the given docid. If an out-of-range docid is given, enacts putDocument/error and throws a BadDocumentIdentifier exception. Otherwise, if the size of the current Document would cause the customer to reach their storage allocation limit, enacts putDocument/blocked and returns a tuple of the available storage and null (no new version). Otherwise, if the docid relates to an existing Document, enacts putDocument/update and stores the Document as the last version in the list of Documents indexed against the docid. Otherwise, the docid is one greater than the last version, and enacts putDocument/new to create a new list to hold versions of the Document and adds the Document. If LoggedOut, enacts putDocument/ignore.

Parameters:

docid - the index of the Document.

document - the Document.

Returns:

a tuple of the remaining storage left; and the latest version number for the Document, or null if the Document was not stored.

Throws:

BadDocumentIdentifier - if an out-of-range docid was provided.

getDocument

public Document getDocument(java.lang.Integer docid)
                     throws BadDocumentIdentifier,
                            BadVersionIdentifier

If LoggedIn, attempts to retrieve a Document with the given docid. If an out-of-range docid is given, enacts getDocument/error and throws a BadDocumentIdentifier exception. Otherwise, if the size of the version list associated with the docid is empty, enacts getDocument/absent and throws a BadVersionIdentifier exception. Otherwise, retrieves the last version of the Document, enacting getDocument/ok and returning a tuple of the Document and its last version number. If LoggedOut, enacts getDocument/ignore.

Parameters:

docid - the index of the Document.

Returns:

the latest version of the Document.

Throws:

BadDocumentIdentifier - if an out-of-range docid was provided.

BadVersionIdentifier - if no versions of this Document exist.

getVersion

public Document getVersion(java.lang.Integer docid,
                  java.lang.Integer version)
                    throws BadDocumentIdentifier,
                           BadVersionIdentifier

If LoggedIn, attempts to retrieve a Document with the given docid and version number. If an out-of-range docid is given, enacts getVersion/error and throws a BadDocumentIdentifier exception. Otherwise, if the version is out-of-range, enacts getVersion/absent and throws a BadVersionIdentifier exception. Otherwise, retrieves the given version of the Document, enacting getVersion/ok and returns the Document. If LoggedOut, enacts getVersion/ignore.

Parameters:

docid - the index of the Document.

version - the version number.

Returns:

the Document.

Throws:

BadDocumentIdentifier - if an out-of-range docid was provided.

BadVersionIdentifier - if an out-of-range version was provided.

deleteVersion

public java.lang.Integer deleteVersion(java.lang.Integer docid,
                              java.lang.Integer version)
                                throws BadDocumentIdentifier,
                                       BadVersionIdentifier

If LoggedIn, attempts to delete a Document with the given docid and version number. If an out-of-range docid is given, enacts deleteVersion/error and throws a BadDocumentIdentifier exception. Otherwise, if the version is out-of-range, enacts deleteVersion/absent and throws a BadVersionIdentifier exception. Otherwise, deletes the given version of the Document, enacting deleteVersion/ok and returns the remaining storage available. If LoggedOut, enacts deleteVersion/ignore.

Parameters:

docid - the index of the Document.

version - the version number.

Returns:

the remaining available storage.

Throws:

BadDocumentIdentifier - if an out-of-range docid was provided.

BadVersionIdentifier - if an out-of-range version was provided.