The goal of this project is to provide core functionality needed to interact with PEF-files, to provide implementations for commonly used software/hardware related to PEF-files and to provide an easy way for others to extend the list of implementations.
The project contains code to:
Soon the following features will be included too:
The software should be:
Code written for this project must work under Java SE 5.
Some operations are best handled using XSLT and XPath. Where these technologies have been used, only the versions directly supported by Java has been used, i.e.
Note that care must be taken not to use XSLT 2.0, since it is readily available in the coding environment. Saxon 8 is used for the validation functionality, but should not be used elsewhere.
The goal to avoid using additional libraries if possible has been successful, except in validation and testing. Therefore, in order to use the PEF validator, the following libraries must be included in the class path:
To run unit tests using Ant, "junit-4.4.jar" must be in the class path.
If validation is not needed, no jar-files have to be included in the distribution.
An online version of the Javadoc is available here (release 1.1.0).
Java Services API is used for discovering implementations at runtime. The reason for using this technology instead of, for example, OSGi, is because the Services API is part of the JRE.
All services that an implementation wants to provide as Java services must be published in the META-INF/services folder. That folder should contain one file for each interface having implementations that should be provided as Java services. The file name must equal the interface's canonical name. The contents of each file should be a list of canonical names of classes implementing the interface indicated by the file name.
The following interfaces have been constructed so that they can be discovered as Java services:
All of these may be discovered by the Services API. However, in most cases, one of the following interfaces will provide a starting point for a developer who wishes to add functionality to the software:
The classes in the org.daisy.factory package provides the foundation for the interfaces used elsewhere in the software to discover and create objects. At the top level is the Provider interface. Its sole purpose is to provide a collection of factories. The factories implement the Factory interface.
Note that the objects created using a Factory implementation are not controlled by these interfaces.
Different factories creating the same type of objects can be combined in a FactoryCatalog. The catalog can then be used to extract a list of all factories that can be used to create a specific type of objects.
The trunk, tags, and branches directories live in the root directory of the repository, and the projects are placed in subdirectories beneath those. The main project (Braille Utils) is located in the "braille" subdirectory (https://brailleutils.googlecode.com/svn/trunk/braille). Additional projects may be added to the repository in the future.
The project contains three source folders:
Core functionality should be placed in the src folder. Interface implementations, such as embossers or papers, should generally be placed in the catalog folder.
Unit tests should be placed in the tests folder, mirroring the structure of the other two source folders. The risk for naming conflicts in the tests folder have been minimized by using different naming schemes for src and catalog.
The catalog folder has a relatively flat structure. Each folder in the catalog folder should contain related implementation entities. Each entity should be modelled on the domain of an organization using a two-part underscore separated string where the first part begins with the top level domain name of the organization and then the organization's domain. If possible, use the organization of the provider of the hardware (or software) that the implementations target. If this is not possible, use the organization of the provider of the implementations (your organization).
Note that this does not imply ownership or responsibility for the code in the package, but merely serves as identification and a structuring aid.
The classes in each of these folders should be considered package specific. Implementations may not rely on other packages in the catalog. If a functionality can be regarded as generic, it should be placed in the src folder instead.
Unit tests can performed by running "build.xml" with Ant.
If applicable, add unit tests to verify your changes and make sure that all unit tests pass before committing code to the project. Also, remember to enter a descriptive commit comment, describing the key aspects of your work.
The distribution is built by running "build.xml" with Ant. "build.xml" can also generate Javadoc and run unit tests. All files related to this process should be placed in the "ant-build" folder. Files created as a result of running "build.xml" should be placed in "ant-build/output" and should not be added to the repository.
...