org.w3c.mwi.mobileok.basic
Class Preprocessor

java.lang.Object
  org.w3c.mwi.mobileok.basic.Preprocessor

public final class Preprocessor
extends java.lang.Object

Creates the intermediate moki representation of an HTTP(S) resource from its URI.

All the tests checked by the mobileOK Checker apply to the intermediate moki representation of the resource under test.

The moki representation of a resource follows the moki schema. It contains retrieval information about the resource under test, as well as information about resources that are embedded in the resource (stylesheets, images, objects) or linked from the resource.

Resources are retrieved asynchronously using multiple threads.

Version:

$Revision: 1.1 $

Author:

The W3C mobileOK Checker Task Force

See Also:

PreprocessorResults

Nested Class Summary

private class

Preprocessor.ProcessingElement Internal private class to hold a Resource along with a boolean that tells whether the resource has been processed or not.

Field Summary

private static java.util.concurrent.ThreadFactory	DAEMON_THREAD_FACTORY Static thread factory that creates daemon threads as opposed to user threads.
private java.util.List<java.lang.Exception>	exceptions List of exceptions that may have been caught while retrieving, decoding and extracting resources.
private java.util.List<Preprocessor.ProcessingElement>	processingElements Intermediate list of resources to process, encapsulated in a processing element to track processing status.
private java.util.List<Resource>	resources Intermediate list of resources to process.
private int	resourcesToProcess Intermediate counter of the number of resources that are yet to process.
private PreprocessorResults	results Internal moki representation built by this Preprocessor.
private java.util.concurrent.ExecutorService	threadPool Thread manager service used to monitor progress on asynchronous resources retrieval.
private java.net.URI	uri The absolute URI of the resource being preprocessed.

Constructor Summary

Preprocessor(java.net.URI uri)
Creates a class instance bound to a URI.

Method Summary

private void	addCaughtException(java.lang.Exception exception) Adds an exception to the list of exceptions caught while retrieving the resources.
private void	addResourcesToProcess(java.util.List<Resource> resourcesToProcess) Adds new resources to process to the intermediate list of resources.
private java.util.List<Resource>	cloneKnownResources() Returns a copy of the list of resources that have already been extracted.
private void	decrNumberOfResourcesToProcess() Decrements the number of resources that have yet to be processed.
private Preprocessor.ProcessingElement	getNextResourceToProcess() Returns the next resource to process.
private int	getNumberOfResourcesToProcess() Returns the number of resources that have yet to be processed.
PreprocessorResults	getPreprocessorResults() Returns the intermediate moki representation of the resource bound to this instance.
void	preprocess() Creates the moki representation of the URI set when this instance was created.
private void	processResource(Resource resource) Processes a resource synchronously, i.e.
private void	processResourceAsynchronously(Resource resource) Processes a resource asynchronously, i.e.

Methods inherited from class java.lang.Object

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

Field Detail

DAEMON_THREAD_FACTORY

private static final java.util.concurrent.ThreadFactory DAEMON_THREAD_FACTORY

Static thread factory that creates daemon threads as opposed to user threads.

Using daemon threads to retrieve resources means that the program may be stopped without having to wait for completion of all the retrieval threads.

threadPool

private final java.util.concurrent.ExecutorService threadPool

Thread manager service used to monitor progress on asynchronous resources retrieval.

uri

private final java.net.URI uri

The absolute URI of the resource being preprocessed.

results

private PreprocessorResults results

Internal moki representation built by this Preprocessor.

resourcesToProcess

private int resourcesToProcess

Intermediate counter of the number of resources that are yet to process.

Do not read/write the counter directly, but rather use thread-safe methods getNumberOfResourcesToProcess() and decrNumberOfResourcesToProcess().

The counter is incremented each time a new resource is extracted and added to the list (see addResourcesToProcess(List)).

The counter must be decremented at the last processing step of a resource, and in particular after new resources have been extracted.

The counter is

resources

private final java.util.List<Resource> resources

Intermediate list of resources to process.

The list needs to be thread-safe, so code must not interact with the list directly, but rather should use the dedicated methods to add and process elements in the list.

processingElements

private final java.util.List<Preprocessor.ProcessingElement> processingElements

Intermediate list of resources to process, encapsulated in a processing element to track processing status.

The list needs to be thread-safe, so code must not interact with the list directly, but rather should use the dedicated methods to add and process elements in the list.

exceptions

private final java.util.List<java.lang.Exception> exceptions

List of exceptions that may have been caught while retrieving, decoding and extracting resources.

Constructor Detail

Preprocessor

public Preprocessor(java.net.URI uri)

Creates a class instance bound to a URI.

Parameters:

uri - URI of the HTTP(S) whose moki representation should be checked.

Method Detail

getPreprocessorResults

public PreprocessorResults getPreprocessorResults()

Returns the intermediate moki representation of the resource bound to this instance.

Returns:

the moki representation of the resource, null when the resource has not been processed yet or could not be processed (an exception would have been raised in that case).

getNumberOfResourcesToProcess

private int getNumberOfResourcesToProcess()

Returns the number of resources that have yet to be processed.

The method is thread-safe and must be used to access the internal resourcesToProcess counter.

Returns:

the number of resources that need to be processed.

decrNumberOfResourcesToProcess

private void decrNumberOfResourcesToProcess()

Decrements the number of resources that have yet to be processed.

The method is thread-safe and must be used to access the internal resourcesToProcess counter.

cloneKnownResources

private java.util.List<Resource> cloneKnownResources()

Returns a copy of the list of resources that have already been extracted.

Resources in the returned list may not have been processed yet.

The list is copied because the original list may be updated by different threads at once. Note that only the list is copied, not the items in the list.

Returns:

a copy of the list of known resources.

getNextResourceToProcess

private Preprocessor.ProcessingElement getNextResourceToProcess()

Returns the next resource to process.

The method is thread-safe and must be used to access the internal list of resources to process processingElements.

The retrieved element is flagged as being processed, which means that the calling method must process it!

The method returns null when there is no resource to process at this time. This does not mean that processing is over though, there may be resources that are still being processed and that may still generate additional resources to process. The getNumberOfResourcesToProcess() method should rather be used to tell whether processing is over.

The method does not decrement the number of resources that have yet to be processed. This needs to be done when the resource has truly been processed, through a call to decrNumberOfResourcesToProcess().

Returns:

the next resource to process, null if there is no resource to process for the time being.

addResourcesToProcess

private void addResourcesToProcess(java.util.List<Resource> resourcesToProcess)

Adds new resources to process to the intermediate list of resources.

Parameters:

resourcesToProcess - list of resources that need to be processed.

addCaughtException

private void addCaughtException(java.lang.Exception exception)

Adds an exception to the list of exceptions caught while retrieving the resources.

Parameters:

exception - Exception to add to the list.

preprocess

public void preprocess()
                throws TestException

Creates the moki representation of the URI set when this instance was created.

The resource identified by the URI and all the resources that are linked to this URI and that take part in the final moki representation will be retrieved and decoded.

Throws:

TestException - an unexpected error occurred.

processResource

private void processResource(Resource resource)

Processes a resource synchronously, i.e. retrieves, decodes and extracts new resources from the given resource.

The number of resources that have yet to be processed is decremented (using decrNumberOfResourcesToProcess()) at the end of the processing.

Parameters:

resource - resource to process

processResourceAsynchronously

private void processResourceAsynchronously(Resource resource)

Processes a resource asynchronously, i.e. creates a thread that processes the resource using processResource(Resource) and returns immediately.

The method may need to wait for a thread to become available in the pool of threads.

Parameters:

resource - resource to process