RE: Sketch of documentation for mobileOK Basic implementation

Hi Sean

This is coming along nicely. Some comments:

[a] afaik the jury is still out on how to actually run the tests. I
think we should leave the architecture open and potentially run two
parallel threads with the procedural team and the declarative team
working in a competitive (albeit supportive, consensus driven and
ultimately collaborative) way.

[b] we need to resolve what we are going to do about validity checking
and the possible need to refer to external validity checkers

[c] Tidy - as mentioned I prefer the idea of Tag Soup on the basis that
it seems to hold out the promise of having a declarative statement of
what it is trying to do, plus Ruadhan has actually used it in the
current version of ready.mobi

[d] I foresee the need to allow various configuration options and thing
there may be a need to refer to a config file to establish context
[though I don't have a clear idea of what might be configured in such a
file at the moment]

[e] given that the intermediate results are likely to call on the
HTTP-in-RDF  spec (which I confess I haven't had time to look at the
latest version, having been immersed in mobileOK for the last few days)
is it appropriate to create a schema for our document formats. Is there
an easy way to turn an RDFS into an XSD for example?

[f] similar ref results


More I'm sure but this is late, it is late and I am hungry.

Jo


> -----Original Message-----
> From: public-mobileok-checker-request@w3.org [mailto:public-mobileok-
> checker-request@w3.org] On Behalf Of Sean Owen
> Sent: 21 March 2007 01:37
> To: public-mobileok-checker@w3.org
> Subject: Sketch of documentation for mobileOK Basic implementation
> 
> 
> Here's the beginnings of a the documentation that we should produce
> along with the reference implementation:
> 
> 
> 1. Overview
> 2. Design Overview
> 3. Usage
> 4. Implementation notes
> 5. Appendices
> 
> 
> 1. Overview
> 
> This document describes the design and usage of the mobileOK Basic
> Tests reference implementation. These are intended to be useful to
> developers who wish to integrate the reference implementation into an
> existing application or infrastructure.
> 
> mobileOK Basic does leaves some decisions up to particular
> implementations, and allows for implementations to provide additional
> functionality. So, this document also discusses
> implementation-specific decisions taken during development. These are
> intended to be useful to developers who are porting this
> implementation to another platform, or, developing a new
> implementation from scratch.
> 
> 
> 2. Design Overview
> 
> The reference implementation provided here is written in Java and
> requires J2SDK 5.0. It is a pure Java library, rather than an
> application. It is intended to be embedded in another application,
> possibly one that provides a GUI or web-based interface to its
> functionality.
> 
> 2.1 Architecture
> 
> (TODO: insert basic architecture diagram)
> 
> In essence, the library accepts as input a URI, and outputs two sets
> of information. First is the set of test results of course. The second
> output summarizes the results of accessing and  pre-processing the URI
> under test. This second output is provided for information, but also
> to aid extensibility.
> 
> 2.2 Design of public API
> 
> (TODO: insert class diagram)
> 
> The key API classes are:
> 
> Tester
> This is the top-level abstraction which runs the test. It can be
> constructed to operate on a file, a URI, or can be given the HTTP
> response body and headers directly. It exposes a runTests() method
> that runs everything, or, runTest() which runs just one test.
> 
> TestType
> Just an enum of all test types.
> 
> TestResults
> TestResult
> Returned by runTests() and runTest() respectively, and encapsulate the
> results of many tests and one test, respectively. TestResults includes
> many TestResult instances. These objects include test outcome,
> warnings, and information.
> 
> TestOutcome
> Just an enum of PASS and FAIL, the two test outcomes
> 
> TestException
> Throw if something goes wrong in the tester -- that is, not just that
> there was an error accessing the document but that something is wrong
> with the tester.
> 
> 
> 3. Usage
> 
> 3.1 Java
> 
> -------------------
> Tester tester = new Tester("http://example.org");
> TestResults results = tester.runTests();
> TestOutcome outcome = results.getOverallOutcome();
> TestResult = results.getResultForTest(TestType.AUTO_REFRESH);
> 
> ...
> TestResult oneResult = tester.runTest(TestType.AUTO_REFRESH);
> -------------------
> 
> 3.2 Command line
> 
> While provided as a library, it is also possible to get quick results
> on the command line:
> 
> -------------------
> java -cp mobileOKBasic-RI.jar org.w3c.mwi.mobileok.basic.Tester
> http://example.org
> -------------------
> 
> 
> 4. Implementation Notes
> 
> This section discusses implementation decisions taken in design and
> development that were not dictated by the mobileOK Basic Tests
> specification.
> 
> 4.1 Preprocessing Results
> 
> The most noticeable feature of this implementation is that it exposes
> a large amount of information about the results of accessing and
> pre-processing the URI under test (see Appendices). This is provided
> from method XXX of class XXX  in Java. It also provided as a DOM which
> may be serialized and used by any external tool. Appendix XX describes
> the format of this DOM in detail. This data structure contains the
> following information:
> 
> TODO
> 
> 4.2 Test Results
> 
> Test results are available from the method Tester.runTests(), which
> returns a TestResults object. The same information is available as a
> DOM from method XXX, in a format described in Appendix XX. The format
> uses the EARL RDF vocabulary to describe the outcome. Test results are
> provided in this form as well to ease integration with external tools.
> The test results data structures include the following information:
> 
> - Overall outcome (PASS or FAIL)
> - Global warning messages
> - Global informational messages
> - For each test:
>   - Test outcome (PASS or FAIL)
>   - Error message if any
>   - Warning messages
>   - Informational messages
> 
> 4.3 Notes to extenders
> 
> This section contains notes that may be useful to developers who wish
> to build on this implementation to construct additional tests of
> mobile content beyond what is defined in mobileOK Basic.
> 
> TODO
> 
> 4.4 Malformed markup and tidying
> 
> It is expected that the most common cause of test failures is
> malformed markup. This will cause the VALID_MARKUP test to fail of
> course, and thus the entire test suite.
> 
> However, many tests must have a valid DOM to run and produce any
> useful information. It is of course desirable to provide as much
> information as possible to the person running the tests rather than
> completely fail on the common case of malformed markup.
> 
> So, in the event that the input document cannot be parsed into a DOM,
> this implementation will attempt to "tidy" the document using
> HtmlCleaner and then re-run all tests. This does not change the fact
> that the overall test suite result is FAIL; however, this does
> potentially allow some tests to run and provide some useful feedback
> to the developer.
> 
> 4.5 Third-party packages
>   Jakarta Commons Codec 1.3
>   Jakarta Commons HttpClient 3.1
>   Jakarta Commons Logging 1.1
>   HtmlCleaner 1.12
> 
> 
> 5. Appendices
> 
> 5.1 Intermediate results
> 5.1.1 Schema
> 5.1.2 Example
> 
> TODO
> 
> 5.2 Test results schema
> 5.2.1 Schema
> 5.2.2 Example
> 
> TODO

Received on Thursday, 29 March 2007 20:16:43 UTC