jqcML API functionality

The full capabilities of the jqcML library are accessible through its API. See the documentation for a detailed description of all classes and methods.

The following typical code examples illustrate how the jqcML API can be used to process different sources of qcML data. The typical jqcML workflow is shown in the following figure.

Reading qcML data

Functionality to read qcML data is available through the QcMLReader interface. Specific classes that implement this interface are QcMLFileReader and QcDBReader, depending on the source of the qcML data.

// create a new qcML file reader
QcMLReader reader = new QcMLFileReader();

// or create a new qcDB reader (example: SQLite)
EntityManagerFactory emf = QcDBManagerFactory.createSQLiteFactory("qcdb.sqlite");
QcMLReader reader = new QcDBReader(emf);

A QcMLFileReader can be created directly, while a QcDBReader needs additional information to connect to the database. This information depends on the type of database we wish to connect with. (Don't forget to close this connection at the end.)

We can start reading qcML data by specifying the file to be read. For a QcMLFileReader the path of the qcML file has to be provided. For a QcDBReader the name of the qcML file as it is specified in the qcml table is required (this will most probably be the file name without the path prefix).

// read the full qcML object
QcML qcml = reader.getQcML("example.qcml");

As the previous example shows, a qcML object can be read in its entirety. A different approach consists of only reading a specific part of the qcML object, for example if the full object is too big to completely read into main memory. A single Cv or QualityAssessment can be read separately by providing their ID, or an iterator can be used to read each individual Cv or QualityAssessment in turn.

// use an iterator to read all QualityAssessments
for(Iterator<QualityAssessment> it = reader.getQualityAssessmentIterator("example.qcml"); it.hasNext(); ) {
    QualityAssessment qa = it.next();
    // do some stuff
}

Writing qcML data

Equivalently to reading qcML data, the interface QcMLWriter provides functionality to write qcML data. Furthermore, its implementing classes are QcMLFileWriter and QcDBWriter.

// create a new qcML file writer
QcMLWriter writer = new QcMLFileWriter();

// or create a new qcDB writer, using the previously defined EntityManagerFactory
QcMLWriter writer = new QcDBWriter(emf);

The QcMLFileWriter only supports writing a full qcML object to a file; writing an individual subcomponent wouldn't result in having a valid qcML file. The QcDBWriter also supports writing an individual Cv to the database.

// write a full qcML object
writer.writeQcML(qcml);

jqcML object model

The jqcML object model provides a complete representation of the qcML data. The following figure shows a simplified representation of the object model for qcML version 0.0.8. For a full overview of all member variables and methods, see the documentation.

Intuitive methods are provided to retrieve specific information. The following example shows how to extract a specific qualityParameter.

QcML qcml;  // read this from a qcML input source or construct it yourself
QualityAssessment qa = qcml.getRunQuality("run_quality_id");
QualityParameter param = qa.getQualityParameter("param_accession");

Conclusion

jqcML can work with both sources of qcML data: the XML-based file format and the qcDB RDBMS. Through common interfaces the source of the data is abstracted; it can be interchanged easily without affecting the subsequent functionality.

The object model is the central point for all these operations. It can be used to create new qcML content (either XML files or in a relational database), or as a middleman to convert between two different sources of qcML data.