macaw.businessLayer
Interface MacawCurationAPI

All Known Implementing Classes:

DemonstrationCurationService, DemonstrationRetrievalService, ProductionCurationService

public interface MacawCurationAPI

Macaw is a data curation application that stores and retrieves its data via methods of this interface. MacawCurationAPI is designed to hide much of the details about data persistence from the GUI code.

Parameters for many of the API methods come from data container classes that are defined in the Macaw Data Model. The concepts such as Variable, RawVariable, DerivedVariable, Category, and ValueLabel represent ideas related to the domain addressed by the NSHD archive. The application packages form data into instances of these classes and submits them to an implementation of MacawDatabase.

Macaw anticipates three main implementations:

• a Production SQL Database (see ProductionCurationService
• an in-memory database ( see DemonstrationCurationService
• a Test SQL Database, which may be either one of the other two, but loaded with data that is intended to be used to test methods more than demonstrate features.

The ProductionCurationService will be the SQL database that holds the data about all NSHD variables that will be advertised using SWIFT. A Test SQL database will be created which uses the same relational schema but the records it contains will be designed to provide a minimal test data set that can be used in automated testing efforts.

The API has been designed to anticipate key operations that would be involved with retrieving or committing changes to a relational database. However, the abstraction is also designed to permit the development of a DemonstrationCurationService that is managed entirely in-memory using collections of data objects instantiated from the Application Model. The 'database' is designed to hold a minimal number of records that can demonstrate to domain users the features provided by Macaw. The in-memory database is used to allow the LHA to run a demonstration version of the application on a memory stick without the need for MySQL to be installed on a client machine and without relying on a database filled with sensitive data about case studies.

Copyright 2010 Medical Research Council Unit for Lifelong Health and Ageing Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Version:

1.0

Author:

Kevin Garwood (kgarwood@users.sourceforge.net)

Method Summary

void	addAliasFilePath(User user, AliasFilePath aliasFilePath)
void	addAvailabilityState(User user, AvailabilityState availabilityState)
void	addCategory(User user, Category category)
void	addCleaningState(User user, CleaningState cleaningState)
void	addDerivedVariable(User user, DerivedVariable derivedVariable)
void	addOntologyTerm(User user, OntologyTerm ontologyTerm)
void	addRawVariable(User user, RawVariable rawVariable)
void	addSupportingDocument(User user, SupportingDocument supportingDocument)
void	addUser(User admin, User user)
void	addValueLabels(User user, Variable variable, java.util.ArrayList<ValueLabel> valueLabels)
void	associateOntologyTermsWithVariable(User user, Variable variable, java.util.ArrayList<OntologyTerm> ontologyTerms)
void	associateSourceVariables(User user, DerivedVariable derivedVariable, java.util.ArrayList<Variable> sourceVariablesToAdd)
void	associateSupportingDocumentsWithVariable(User user, Variable variable, java.util.ArrayList<SupportingDocument> supportingDocument)
void	checkValidAdministrator(User administrator)
void	checkValidUser(User user)
void	clear(User admin)
void	clearAllChanges(User admin)
void	deleteAliasFilePaths(User user, java.util.ArrayList<AliasFilePath> aliasFilePaths)
void	deleteAvailabilityStates(User user, java.util.ArrayList<AvailabilityState> availabilityStates)
void	deleteCategories(User user, java.util.ArrayList<Category> categories)
void	deleteCleaningStates(User user, java.util.ArrayList<CleaningState> cleaningStates)
void	deleteDerivedVariables(User user, java.util.ArrayList<DerivedVariable> derivedVariables)
void	deleteOntologyTerms(User user, java.util.ArrayList<OntologyTerm> ontologyTerms)
void	deleteRawVariables(User user, java.util.ArrayList<RawVariable> rawVariables)
void	deleteSupportingDocuments(User user, java.util.ArrayList<SupportingDocument> supportingDocuments)
void	deleteUsers(User admin, java.util.ArrayList<User> usersToDelete)
void	deleteValueLabels(User user, Variable variable, java.util.ArrayList<ValueLabel> valueLabels)
void	disassociateOntologyTermsFromVariable(User user, Variable variable, java.util.ArrayList<OntologyTerm> ontologyTerms)
void	disassociateSourceVariables(User user, DerivedVariable derivedVariable, java.util.ArrayList<Variable> sourceVariablesToDelete) removes references to either RawVariable or DerivedVariable variables that were used to create a given derivedVariable
void	disassociateSupportingDocumentsFromVariable(User user, Variable variable, java.util.ArrayList<SupportingDocument> supportingDocuments)
java.util.ArrayList<OntologyTerm>	filterOntologyTerms(User user, java.lang.String term, java.lang.String description)
java.util.ArrayList<SupportingDocument>	filterSupportingDocuments(User user, java.lang.String documentTitle, java.lang.String documentCode)
java.util.ArrayList<VariableSummary>	filterVariableSummaries(User user, java.lang.String searchText, java.lang.String year, java.lang.String category, VariableTypeFilter variableTypeFilter)
int	getAliasFilePathIdentifier(User user, Variable variable, AliasFilePath aliasFilePath)
java.util.ArrayList<AliasFilePath>	getAliasFilePaths(User user)
java.util.ArrayList<MacawChangeEvent>	getAllChanges(User admin)
java.util.ArrayList<OntologyTerm>	getAllOntologyTerms(User user)
java.util.ArrayList<SupportingDocument>	getAllSupportingDocuments(User user)
Variable	getAlternativeVariable(User user, Variable targetVariable)
int	getAvailabilityStateIdentifier(User user, Variable variable, AvailabilityState availabilityState)
java.util.ArrayList<AvailabilityState>	getAvailabilityStates(User user)
java.util.ArrayList<Category>	getCategories(User user)
int	getCategoryIdentifier(User user, Variable variable, Category category)
java.util.ArrayList<MacawChangeEvent>	getChangeHistoryByUser(User user)
java.util.ArrayList<MacawChangeEvent>	getChangeHistoryForListChoices(User user)
java.util.ArrayList<MacawChangeEvent>	getChangeHistoryForSupportingDocument(User user, SupportingDocument supportingDocument)
java.util.ArrayList<MacawChangeEvent>	getChangeHistoryForValueLabels(User user, Variable variable)
java.util.ArrayList<MacawChangeEvent>	getChangeHistoryForVariable(User user, Variable variable)
int	getCleaningStateIdentifier(User user, Variable variable, CleaningState cleaningState)
java.util.ArrayList<CleaningState>	getCleaningStates(User user)
Variable	getCompleteVariableData(User user, VariableSummary variableSummary)
int	getDerivedVariableIdentifier(User user, DerivedVariable derivedVariable)
java.lang.String	getFilePathFromAlias(User user, java.lang.String currentAlias)
int	getOntologyTermIdentifier(User user, OntologyTerm ontologyTerm)
java.util.ArrayList<OntologyTerm>	getOntologyTerms(User user, Variable variable)
Variable	getOriginalVariable(User user, Variable variable)
int	getRawVariableIdentifier(User user, RawVariable rawVariable)
java.util.ArrayList<Variable>	getSourceVariables(User user, DerivedVariable derivedVariable)
java.lang.String[]	getStudyYears(User user) retrieves a collection of unique years associated with at least one variable in the data repository.
java.util.ArrayList<VariableSummary>	getSummaryDataForAllVariables(User user) retrieves a collection of all variables managed by the system.
int	getSupportingDocumentIdentifier(User user, SupportingDocument supportingDocument)
java.util.ArrayList<SupportingDocument>	getSupportingDocuments(User user, Variable variable)
int	getUserIdentifier(User admin, User user)
java.util.ArrayList<User>	getUsers(User admin)
int	getValueLabelIdentifier(User user, Variable variable, ValueLabel valueLabel)
java.util.ArrayList<ValueLabel>	getValueLabels(User user, Variable variable)
Variable	getVariable(User user, java.lang.String variableName)
void	setAlternativeVariable(User user, Variable targetVariable, Variable alternativeVariable)
void	updateAliasFilePath(User user, AliasFilePath aliasFilePath)
void	updateAvailabilityState(User user, AvailabilityState availabilityState)
void	updateCategory(User user, Category category)
void	updateCleaningState(User user, CleaningState cleaningState)
void	updateDerivedVariable(User user, DerivedVariable derivedVariable)
void	updateOntologyTerm(User user, OntologyTerm ontologyTerm)
void	updateRawVariable(User user, RawVariable rawVariable)
void	updateSupportingDocument(User user, SupportingDocument supportingDocument)
void	updateUser(User admin, User user)
void	updateValueLabels(User user, Variable variable, java.util.ArrayList<ValueLabel> valueLabels)

Method Detail

addRawVariable

void addRawVariable(User user,
                    RawVariable rawVariable)
                    throws MacawException

Throws:

MacawException

deleteRawVariables

void deleteRawVariables(User user,
                        java.util.ArrayList<RawVariable> rawVariables)
                        throws MacawException

Throws:

MacawException

updateRawVariable

void updateRawVariable(User user,
                       RawVariable rawVariable)
                       throws MacawException

Throws:

MacawException

getRawVariableIdentifier

int getRawVariableIdentifier(User user,
                             RawVariable rawVariable)
                             throws MacawException

Throws:

MacawException

addDerivedVariable

void addDerivedVariable(User user,
                        DerivedVariable derivedVariable)
                        throws MacawException

Throws:

MacawException

deleteDerivedVariables

void deleteDerivedVariables(User user,
                            java.util.ArrayList<DerivedVariable> derivedVariables)
                            throws MacawException

Throws:

MacawException

updateDerivedVariable

void updateDerivedVariable(User user,
                           DerivedVariable derivedVariable)
                           throws MacawException

Throws:

MacawException

getDerivedVariableIdentifier

int getDerivedVariableIdentifier(User user,
                                 DerivedVariable derivedVariable)
                                 throws MacawException

Throws:

MacawException

getVariable

Variable getVariable(User user,
                     java.lang.String variableName)
                     throws MacawException

Throws:

MacawException

getValueLabels

java.util.ArrayList<ValueLabel> getValueLabels(User user,
                                               Variable variable)
                                               throws MacawException

Throws:

MacawException

addValueLabels

void addValueLabels(User user,
                    Variable variable,
                    java.util.ArrayList<ValueLabel> valueLabels)
                    throws MacawException

Throws:

MacawException

updateValueLabels

void updateValueLabels(User user,
                       Variable variable,
                       java.util.ArrayList<ValueLabel> valueLabels)
                       throws MacawException

Throws:

MacawException

deleteValueLabels

void deleteValueLabels(User user,
                       Variable variable,
                       java.util.ArrayList<ValueLabel> valueLabels)
                       throws MacawException

Throws:

MacawException

getValueLabelIdentifier

int getValueLabelIdentifier(User user,
                            Variable variable,
                            ValueLabel valueLabel)
                            throws MacawException

Throws:

MacawException

getAllSupportingDocuments

java.util.ArrayList<SupportingDocument> getAllSupportingDocuments(User user)
                                                                  throws MacawException

Throws:

MacawException

getSupportingDocuments

java.util.ArrayList<SupportingDocument> getSupportingDocuments(User user,
                                                               Variable variable)
                                                               throws MacawException

Throws:

MacawException

addSupportingDocument

void addSupportingDocument(User user,
                           SupportingDocument supportingDocument)
                           throws MacawException

Throws:

MacawException

updateSupportingDocument

void updateSupportingDocument(User user,
                              SupportingDocument supportingDocument)
                              throws MacawException

Throws:

MacawException

deleteSupportingDocuments

void deleteSupportingDocuments(User user,
                               java.util.ArrayList<SupportingDocument> supportingDocuments)
                               throws MacawException

Throws:

MacawException

getSupportingDocumentIdentifier

int getSupportingDocumentIdentifier(User user,
                                    SupportingDocument supportingDocument)
                                    throws MacawException

Throws:

MacawException

associateSupportingDocumentsWithVariable

void associateSupportingDocumentsWithVariable(User user,
                                              Variable variable,
                                              java.util.ArrayList<SupportingDocument> supportingDocument)
                                              throws MacawException

Throws:

MacawException

disassociateSupportingDocumentsFromVariable

void disassociateSupportingDocumentsFromVariable(User user,
                                                 Variable variable,
                                                 java.util.ArrayList<SupportingDocument> supportingDocuments)
                                                 throws MacawException

Throws:

MacawException

getSourceVariables

java.util.ArrayList<Variable> getSourceVariables(User user,
                                                 DerivedVariable derivedVariable)
                                                 throws MacawException

Throws:

MacawException

associateSourceVariables

void associateSourceVariables(User user,
                              DerivedVariable derivedVariable,
                              java.util.ArrayList<Variable> sourceVariablesToAdd)
                              throws MacawException

Throws:

MacawException

disassociateSourceVariables

void disassociateSourceVariables(User user,
                                 DerivedVariable derivedVariable,
                                 java.util.ArrayList<Variable> sourceVariablesToDelete)
                                 throws MacawException

removes references to either RawVariable or DerivedVariable variables that were used to create a given derivedVariable

Parameters:

user -

derivedVariable - contains source variables to delete

sourceVariablesToDelete - the raw or derived variables that should no longer be associated with derivedVariable.

Throws:

MacawException

getStudyYears

java.lang.String[] getStudyYears(User user)
                                 throws MacawException

retrieves a collection of unique years associated with at least one variable in the data repository.

Parameters:

user -

Throws:

MacawException

getSummaryDataForAllVariables

java.util.ArrayList<VariableSummary> getSummaryDataForAllVariables(User user)
                                                                   throws MacawException

retrieves a collection of all variables managed by the system. These variables will include instances of RawVariables and DerivedVariable. Note that only summary data are included:

Parameters:

user -

Throws:

MacawException

getCompleteVariableData

Variable getCompleteVariableData(User user,
                                 VariableSummary variableSummary)
                                 throws MacawException

Throws:

MacawException

filterVariableSummaries

java.util.ArrayList<VariableSummary> filterVariableSummaries(User user,
                                                             java.lang.String searchText,
                                                             java.lang.String year,
                                                             java.lang.String category,
                                                             VariableTypeFilter variableTypeFilter)
                                                             throws MacawException

Throws:

MacawException

filterSupportingDocuments

java.util.ArrayList<SupportingDocument> filterSupportingDocuments(User user,
                                                                  java.lang.String documentTitle,
                                                                  java.lang.String documentCode)
                                                                  throws MacawException

Throws:

MacawException

filterOntologyTerms

java.util.ArrayList<OntologyTerm> filterOntologyTerms(User user,
                                                      java.lang.String term,
                                                      java.lang.String description)
                                                      throws MacawException

Throws:

MacawException

getCategories

java.util.ArrayList<Category> getCategories(User user)
                                            throws MacawException

Parameters:

user -

Returns:

a collection of categories used to classify NSHD variables. eg: "General Health" and "Education".

Throws:

MacawException

addCategory

void addCategory(User user,
                 Category category)
                 throws MacawException

Throws:

MacawException

updateCategory

void updateCategory(User user,
                    Category category)
                    throws MacawException

Throws:

MacawException

deleteCategories

void deleteCategories(User user,
                      java.util.ArrayList<Category> categories)
                      throws MacawException

Throws:

MacawException

getCategoryIdentifier

int getCategoryIdentifier(User user,
                          Variable variable,
                          Category category)
                          throws MacawException

Throws:

MacawException

getCleaningStates

java.util.ArrayList<CleaningState> getCleaningStates(User user)
                                                     throws MacawException

Throws:

MacawException

addCleaningState

void addCleaningState(User user,
                      CleaningState cleaningState)
                      throws MacawException

Throws:

MacawException

updateCleaningState

void updateCleaningState(User user,
                         CleaningState cleaningState)
                         throws MacawException

Throws:

MacawException

deleteCleaningStates

void deleteCleaningStates(User user,
                          java.util.ArrayList<CleaningState> cleaningStates)
                          throws MacawException

Throws:

MacawException

getCleaningStateIdentifier

int getCleaningStateIdentifier(User user,
                               Variable variable,
                               CleaningState cleaningState)
                               throws MacawException

Throws:

MacawException

getAvailabilityStates

java.util.ArrayList<AvailabilityState> getAvailabilityStates(User user)
                                                             throws MacawException

Throws:

MacawException

addAvailabilityState

void addAvailabilityState(User user,
                          AvailabilityState availabilityState)
                          throws MacawException

Throws:

MacawException

updateAvailabilityState

void updateAvailabilityState(User user,
                             AvailabilityState availabilityState)
                             throws MacawException

Throws:

MacawException

deleteAvailabilityStates

void deleteAvailabilityStates(User user,
                              java.util.ArrayList<AvailabilityState> availabilityStates)
                              throws MacawException

Throws:

MacawException

getAvailabilityStateIdentifier

int getAvailabilityStateIdentifier(User user,
                                   Variable variable,
                                   AvailabilityState availabilityState)
                                   throws MacawException

Throws:

MacawException

getAliasFilePaths

java.util.ArrayList<AliasFilePath> getAliasFilePaths(User user)
                                                     throws MacawException

Throws:

MacawException

addAliasFilePath

void addAliasFilePath(User user,
                      AliasFilePath aliasFilePath)
                      throws MacawException

Throws:

MacawException

updateAliasFilePath

void updateAliasFilePath(User user,
                         AliasFilePath aliasFilePath)
                         throws MacawException

Throws:

MacawException

deleteAliasFilePaths

void deleteAliasFilePaths(User user,
                          java.util.ArrayList<AliasFilePath> aliasFilePaths)
                          throws MacawException

Throws:

MacawException

getAliasFilePathIdentifier

int getAliasFilePathIdentifier(User user,
                               Variable variable,
                               AliasFilePath aliasFilePath)
                               throws MacawException

Throws:

MacawException

getFilePathFromAlias

java.lang.String getFilePathFromAlias(User user,
                                      java.lang.String currentAlias)
                                      throws MacawException

Throws:

MacawException

getAllOntologyTerms

java.util.ArrayList<OntologyTerm> getAllOntologyTerms(User user)
                                                      throws MacawException

Throws:

MacawException

getOntologyTerms

java.util.ArrayList<OntologyTerm> getOntologyTerms(User user,
                                                   Variable variable)
                                                   throws MacawException

Throws:

MacawException

addOntologyTerm

void addOntologyTerm(User user,
                     OntologyTerm ontologyTerm)
                     throws MacawException

Throws:

MacawException

updateOntologyTerm

void updateOntologyTerm(User user,
                        OntologyTerm ontologyTerm)
                        throws MacawException

Throws:

MacawException

deleteOntologyTerms

void deleteOntologyTerms(User user,
                         java.util.ArrayList<OntologyTerm> ontologyTerms)
                         throws MacawException

Throws:

MacawException

getOntologyTermIdentifier

int getOntologyTermIdentifier(User user,
                              OntologyTerm ontologyTerm)
                              throws MacawException

Throws:

MacawException

associateOntologyTermsWithVariable

void associateOntologyTermsWithVariable(User user,
                                        Variable variable,
                                        java.util.ArrayList<OntologyTerm> ontologyTerms)
                                        throws MacawException

Throws:

MacawException

disassociateOntologyTermsFromVariable

void disassociateOntologyTermsFromVariable(User user,
                                           Variable variable,
                                           java.util.ArrayList<OntologyTerm> ontologyTerms)
                                           throws MacawException

Throws:

MacawException

getChangeHistoryForVariable

java.util.ArrayList<MacawChangeEvent> getChangeHistoryForVariable(User user,
                                                                  Variable variable)
                                                                  throws MacawException

Throws:

MacawException

getChangeHistoryForSupportingDocument

java.util.ArrayList<MacawChangeEvent> getChangeHistoryForSupportingDocument(User user,
                                                                            SupportingDocument supportingDocument)
                                                                            throws MacawException

Throws:

MacawException

getChangeHistoryForValueLabels

java.util.ArrayList<MacawChangeEvent> getChangeHistoryForValueLabels(User user,
                                                                     Variable variable)
                                                                     throws MacawException

Throws:

MacawException

getChangeHistoryForListChoices

java.util.ArrayList<MacawChangeEvent> getChangeHistoryForListChoices(User user)
                                                                     throws MacawException

Throws:

MacawException

getChangeHistoryByUser

java.util.ArrayList<MacawChangeEvent> getChangeHistoryByUser(User user)
                                                             throws MacawException

Throws:

MacawException

getUsers

java.util.ArrayList<User> getUsers(User admin)
                                   throws MacawException

Throws:

MacawException

addUser

void addUser(User admin,
             User user)
             throws MacawException

Throws:

MacawException

updateUser

void updateUser(User admin,
                User user)
                throws MacawException

Throws:

MacawException

deleteUsers

void deleteUsers(User admin,
                 java.util.ArrayList<User> usersToDelete)
                 throws MacawException

Throws:

MacawException

getUserIdentifier

int getUserIdentifier(User admin,
                      User user)
                      throws MacawException

Throws:

MacawException

checkValidUser

void checkValidUser(User user)
                    throws MacawException

Throws:

MacawException

checkValidAdministrator

void checkValidAdministrator(User administrator)
                             throws MacawException

Throws:

MacawException

clear

void clear(User admin)
           throws MacawException

Throws:

MacawException

clearAllChanges

void clearAllChanges(User admin)
                     throws MacawException

Throws:

MacawException

getAllChanges

java.util.ArrayList<MacawChangeEvent> getAllChanges(User admin)
                                                    throws MacawException

Throws:

MacawException

getOriginalVariable

Variable getOriginalVariable(User user,
                             Variable variable)
                             throws MacawException

Throws:

MacawException

getAlternativeVariable

Variable getAlternativeVariable(User user,
                                Variable targetVariable)
                                throws MacawException

Throws:

MacawException

setAlternativeVariable

void setAlternativeVariable(User user,
                            Variable targetVariable,
                            Variable alternativeVariable)
                            throws MacawException

Throws:

MacawException