Package gov.nist.secauto.decima.core.assessment.result

Interface AssessmentResultBuilder

All Known Implementing Classes:

DefaultAssessmentResultBuilder

public interface AssessmentResultBuilder

Implementations of this interface can be used to build an AssessmentResults based on results reported to the builder during an assessment. An AssessmentResultBuilder is used by the various Assessment implementations to track a collection of TestResult instances generated during the assessment process. new TestResult instances can be registered by calling the addTestResult(Assessment, Document, String, TestResult) method. Once all assessments are completed, an AssessmentResults instance can be generated using the build(RequirementsManager) method. Before calling the DefaultAssessmentResultBuilder.build(RequirementsManager), callers must first call the DefaultAssessmentResultBuilder.end() method to designate the end of the assessment run.

This interface supports marking specific derived requirements as tested by calling the assignTestStatus(Assessment, Document, String, TestState) method. This can be useful to ensure that the derived requirement ResultStatus does not get evaluated as ResultStatus.NOT_TESTED when a TestResult has not been generated for the derived requirement because there was no failure to report using the addTestResult(Assessment, Document, String, TestResult) method.

Method Summary

Modifier and Type	Method	Description
AssessmentResultBuilder	addAssessmentTarget(Document document)	Allows the target of an assessment to be registered and tracked.
<DOC extends Document> AssessmentResultBuilder	addTestResult(Assessment<? extends DOC> assessment, DOC document, String derivedRequirementId, TestResult result)	Appends a new TestResult to the collection of test results associated with the provided derived requirement identifier.
AssessmentResultBuilder	assignProperty(String key, String value)	Allows arbitrary assessment properties to be associated with the results.
<DOC extends Document> AssessmentResultBuilder	assignTestStatus(Assessment<? extends DOC> assessment, DOC document, String derivedRequirementId, TestState state)	Marks the derived requirement associated with the provided identifier as having a specific TestState.
AssessmentResults	build(RequirementsManager requirementsManager)	Generates a new AssessmentResults instance based on the previously recorded TestResult records and other statuses provided to the builder..
AssessmentResultBuilder	end()	Calling this method signals the end of the assessment.
LoggingHandler	getLoggingHandler()	Retrieves a handler that is used to process various assessment event callback methods.
Map<String,TestState>	getTestStateByDerivedRequirementId()	Retrieves the mapping of derived requirement identifiers to TestState.
void	setLoggingHandler(LoggingHandler handler)
AssessmentResultBuilder	start()	Calling this method signals the start of the assessment.

Method Detail

getTestStateByDerivedRequirementId

Map<String,TestState> getTestStateByDerivedRequirementId()

Retrieves the mapping of derived requirement identifiers to TestState. To be tested the derived requirement must: 1) have an associated TestResult provided by calling the addTestResult(Assessment, Document, String, TestResult) method, or 2) be declared as a specific TestState by calling the assignTestStatus(Assessment, Document, String, TestState) method.

Returns:

a map of derived requirement identifiers to the corresponding test status

start

AssessmentResultBuilder start()

Calling this method signals the start of the assessment. The assessment will be automatically started the first time either addTestResult(Assessment, Document, String, TestResult) or assignTestStatus(Assessment, Document, String, TestState) is called. Multiple calls to this method will not change the start time from the initial time.

Returns:

the same builder instance

end

AssessmentResultBuilder end()

Calling this method signals the end of the assessment.

Returns:

the same builder instance

addAssessmentTarget

AssessmentResultBuilder addAssessmentTarget(Document document)

Allows the target of an assessment to be registered and tracked. This can be called multiple times for the same target without causing duplicate targets to be registered. It is expected that an Assessment will call this method at least once.

Parameters:

document - the target of the assessment

Returns:

the same builder instance

assignProperty

AssessmentResultBuilder assignProperty(String key,
                                       String value)

Allows arbitrary assessment properties to be associated with the results. This can be used to include meta information in the assessment results produced.

Parameters:

key - the property key

value - the property value

Returns:

this builder

addTestResult

<DOC extends Document> AssessmentResultBuilder addTestResult(Assessment<? extends DOC> assessment,
                                                             DOC document,
                                                             String derivedRequirementId,
                                                             TestResult result)

Appends a new TestResult to the collection of test results associated with the provided derived requirement identifier.

Type Parameters:

DOC - the type of document that is the target of the assessment

Parameters:

assessment - the target assessment

document - the document being assessed

derivedRequirementId - the derived requirement that the test result is associated with

result - the test result to append

Returns:

the same builder instance

assignTestStatus

<DOC extends Document> AssessmentResultBuilder assignTestStatus(Assessment<? extends DOC> assessment,
                                                                DOC document,
                                                                String derivedRequirementId,
                                                                TestState state)

Marks the derived requirement associated with the provided identifier as having a specific TestState. This method is called when the addTestResult(Assessment, Document, String, TestResult) method is called. If no test result is reported for a given derived requirement, then this method needs to be called to indicate the actual test state of a derived requirement.

Type Parameters:

DOC - the type of document that is the target of the assessment

Parameters:

assessment - the target assessment

document - the document being assessed

derivedRequirementId - the derived requirement to set the state for

state - the state to assign

Returns:

the current builder instance

build

AssessmentResults build(RequirementsManager requirementsManager)

Generates a new AssessmentResults instance based on the previously recorded TestResult records and other statuses provided to the builder..

Note: end() must be called before this method to terminate the assessment.

Parameters:

requirementsManager - the set of requirements corresponding to the assessments performed

Returns:

a new assessment result instance

Throws:

IllegalStateException - if the end() method hasn't first been called

getLoggingHandler

LoggingHandler getLoggingHandler()

Retrieves a handler that is used to process various assessment event callback methods.

Returns:

a non-null handler instance

setLoggingHandler

void setLoggingHandler(LoggingHandler handler)