# Introduction

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.

# Main Features

The project contains code to:

- Emboss a PEF-file
- Validate a PEF-file
- Collect meta data about a PEF-file
- Convert from text to a PEF-file
- Convert from a PEF-file to text
- Implement embossers, tables and papers

Soon the following features will be included too:

- Split a PEF-file into one file/volume
- Merge several PEF-files into one

# Design

The software should be:

- Small
- Extensible
- Platform independent
- Independent from third party libraries
- Informative enough to build user friendly user interfaces on
- Runnable as a Jar-file

Code written for this project must work under Java SE 5.

## XSLT and XPath

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.

- XSLT 1.0
- XPath 1.0

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.

## Jar Libraries

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:

- isorelax.jar
- jing.jar
- saxon8.jar
- xercesImpl.jar
- xml-apis.jar

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.

## Javadoc

An online version of the Javadoc is available here (release 1.1.0).

## Services API

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.

### Services Implementations

The following interfaces have been constructed so that they can be discovered as Java services:

- org.daisy.braille.embosser.EmbosserProvider
- org.daisy.braille.embosser.EmbosserCatalog
- org.daisy.braille.table.TableProvider
- org.daisy.braille.table.TableCatalog
- org.daisy.paper.PaperProvider
- org.daisy.paper.PaperCatalog
- org.daisy.validator.Validator

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:

- org.daisy.braille.embosser.EmbosserProvider
- org.daisy.braille.table.TableProvider
- org.daisy.paper.PaperProvider

## Factory Classes

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.

# Repository Layout

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.

## Braille Utils SVN Layout

The project contains three source folders:

- src
- catalog
- tests

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`.

### Catalog Layout

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.

# Testing

Unit tests can performed by running "build.xml" with Ant.

# Committing code

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.

# Building the Project

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.

## Publishing the Project Build

...