View on GitHub

akomantoso-lib

a Java API for creating and editing Akoma Ntoso XML documents

Download this project as a .zip file Download this project as a tar.gz file

AkomaNtoso-lib provides a Java API for the AkomaNtoso schema. An AkomaNtoso XML document can be imported into its Java object representation, and also converted back to XML. The library packages and supports versions 2 (final) and 3 (draft releases from 6 upto 10: csd06 -> csd10) of the schema. Akoma Ntoso XML documents and Akoma Ntoso objects can be validated using the library.

Releases

The library is released as source code, and as a ready to use JAR file, Click Here for the JAR file !.

The library is also published as an artifact on maven central. Use the following metadata information in your pom.xml file :

<dependency>
  <groupId>io.github.kohsah</groupId>
  <artifactId>akomantoso-lib</artifactId>
  <version>1.0.15</version>
</dependency>

Dependencies

The only dependency is sl4j the logging facade library

Usage

Creating an Akoma Ntoso document using the Java API

First we specify the version and create a marshaller object :

AnVesion ver = new AnVersion(3, "CSD06");
JAXBContext jc = ver.getContext();
Marshaller marshaller = jc.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, 
        true);

Next create the Akoma Ntoso akomaNtoso root element :

// create the root akomaNtoso element
ObjectFactory of = new ObjectFactory();
AkomaNtosoType anType = new AkomaNtosoType();
JAXBElement<AkomaNtosoType> rootElem = 
    of.createAkomaNtoso(anType);

Next create a doc element which is an open structure type, and set its @name and @contains attributes: 

OpenStructure ost = new OpenStructure();
ost.setName("test_doc");
ost.setContains(VersionType.SINGLE_VERSION);

Add a meta element to hold the documents metadata :

// create the meta element
Meta meta = new Meta();

Add a publication within the meta element:

// create the publication tag
Publication pub = new Publication();
pub.setCurrentId("test_pub");
pub.setName("pub");
pub.setDate("2013-01-01");
pub.setNumber("42");
// add the publication element to the meta element
meta.setPublication(pub);

Now create the identification element in meta :

//create the identification element
Identification idf = new Identification();
idf.setSource("#a_source");

Create the FRBRWork element and its child elements :

//create a work element
FRBRWork work = of.createFRBRWork();
//set FRBRthis on work
ValueType vThis = new ValueType();
vThis.setValue("/ak/bill/2013-01-01/A1/memorandum");
work.setFRBRthis(vThis);
//set FRBRuri on work
ValueType vURI = new ValueType();
vURI.setValue("/ak/bill/2013-01-01/A1");
work.getFRBRuri().add(vURI);
//add the identification to the work
idf.setFRBRWork(work);

Add the identification element to the meta element ; and the meta to the document :

//add the identifcatin on the meta
meta.setIdentification(idf);
//add the meta 
ost.setMeta(meta);
//add the doc type to the akomaNtoso element
anType.setDoc(ost);
marshaller.marshal(rootElem, System.out);

The above code outputs an Akoma Ntoso document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<akomaNtoso 
  xmlns="http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD06">
  <doc contains="singleVersion" name="test_doc">
    <meta>
      <identification source="#a_source">
        <FRBRWork>
          <FRBRthis value="/ak/bill/2013-01-01/A1/memorandum"/>
          <FRBRuri value="/ak/bill/2013-01-01/A1"/>
        </FRBRWork>
      </identification>
      <publication date="2013-01-01" number="42" name="pub" 
          currentId="test_pub"/>
    </meta>
  </doc>
</akomaNtoso>

Parsing an Akoma Ntoso XML document, and loading it as an Object

First specify the version:

 AnVersion _version = new AnVersion(3, "CSD07");

Currently, all Akoma Ntoso versions upto the CSD10 release are supported.

Next, specify the file you want to load:

 // file to parse and discover type
 File _parse  = new File("./src/test/java/testdocs/akomantoso_doc_csd07.xml");

This can also be an InputStream, Reader or URI.

Now call the parse() api:

AnDocType resultDoc = AnParser.parse(_version, _parse);

This will return a AnDocType object containing:

Via, the returned objType you can access all the methods of the returned document type.

Loading an XML document, and modifying it with the API

This is a more involved way of doing the same as was described in the previous section. Here you need to explicitly call getAct() / getBill() / getDebate() as the case may be to access the actual document type information.

The following loads an Akoma Ntoso document, and makes it accessible as a Java object: 

// load the context for the specific AKoma Ntoso version you want to use,
// here we use the 3.0-csd06 version
// open a Akoma Ntoso file
File _anDoc = new File("/path/to/akomantoso_doc.xml");
// use version 3 csd06
AnVersion vSchema = new AnVersion(3, "CSD06");
JAXBContext cxt = vSchema.getContext();
Unmarshaller unmarshaller = cxt.createUnmarshaller();
JAXBElement<AkomaNtosoType> anType = 
    (JAXBElement<AkomaNtosoType>)unmarshaller.unmarshal(_anDoc);

After unmarshalling, the document is available for reading & modification via the API : 

AkomaNtosoType anDoc  = anType.getValue();
String aName = anDoc.getDoc().getName();
System.out.println(" doc name = " + aName);
VersionType vType = anDoc.getDoc().getContains();
System.out.println(" doc contains = " + vType.getValue());

If the imported document looked like this :

<akomaNtoso 
 xmlns="http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD06">
    <doc name="memorandum" contains="originalVersion">
        <meta>

The java code above will output :

doc name = memorandum
doc contains = originalVersion

Building from Source

The library is built using maven, to build from source :

git clone https://github.com/kohsah/akomantoso-lib.git -b master
mvn package

Javadoc

Current Javadoc for the library can be located here.

License

Licensed using the Apache 2.0 license