gate.lib.basicdocument

Class BdocDocumentBuilder

java.lang.Object

gate.lib.basicdocument.BdocDocumentBuilder

public class BdocDocumentBuilder
extends Object

Class for building a JsonDocument. This allows building the document from a GATE document or from scratch, optionally limiting the parts to add to the document. Once all the parts are ready, this can be used to return the BdocDocument instance or directly serialise it as JSON to various destinations.

Author:

Johann Petrak [email protected]

Constructor Summary

Constructors

Constructor and Description
BdocDocumentBuilder()

Method Summary

Modifier and Type	Method and Description
BdocDocumentBuilder	addFeature(String name, Object value) Add/set a single feature as a document feature.
BdocDocumentBuilder	addFeatures(Map<Object,Object> fm) Add all features from the given (feature) map as document features.
BdocDocumentBuilder	addSet(String name, Set<gate.Annotation> annset, int nextAnnotationId) Add an annotation set.
BdocDocument	buildBdoc() Given all the info accumulated, build a JsonDocument and return it.
BdocDocumentBuilder	fromGate(gate.Document doc) Tell the builder to create the JsonDocument from a GATE document.
BdocDocumentBuilder	javaOffsets() Make the JsonDocument use java offsets (the default).
BdocDocumentBuilder	pythonOffsets() Make the JsonDocument use python/unicode codepoint offsets.
BdocDocumentBuilder	setAnnotationSetNames(Collection<String> names) Set the list of included AnnotationSet names.
BdocDocumentBuilder	setFeatureNames(Collection<String> featurenames) Set the list of included features.
BdocDocumentBuilder	setIncludePlaceholderSets(boolean flag) Set if placeholders sets should get included.
BdocDocumentBuilder	setName(String name) Set/update the name of the bdoc document.
BdocDocumentBuilder	setText(String text) Set/update the text of the document.
void	toJson(File path) Store the BdocDocument to a file.
void	toJson(OutputStream os) Write the BdocDocument to the output stream.
void	toJson(String path) Store the BdocDocument to a file.
String	toJsonString() Convert the BdocDocument to a JSON string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BdocDocumentBuilder

public BdocDocumentBuilder()

Method Detail

fromGate

public BdocDocumentBuilder fromGate(gate.Document doc)

Tell the builder to create the JsonDocument from a GATE document. By default, this will include all features and all annotation sets, but this can be changed later. Alternately, the JsonDocument can be constructed by adding the parts (text, document features, annotation sets) individually.

Parameters:

doc - the Gate document to build the BdocDocument/JSON from

Returns:

modified BdocDocumentBuilder

addSet

public BdocDocumentBuilder addSet(String name,
                                  Set<gate.Annotation> annset,
                                  int nextAnnotationId)

Add an annotation set. Same as addSet(name, annset) but the annotation set uses the given nextAnnotationId for new annotations. NOTE: if the maximum annotation id in the set is bigger than the given nextAnnotationId, then the bigger Id is used instead!

Parameters:

name - the name of the annotation set (this can differ from the original name if an annotation set is passed. Must not be null, the "default" set uses the empty string as name.

annset - a set of annotations, could be an AnnotationSet or a set of annotations.

nextAnnotationId - the annotation id to start from when new annotations are added to this set in the Bdoc document.

Returns:

modified BdocDocumentBuilder

addFeatures

public BdocDocumentBuilder addFeatures(Map<Object,Object> fm)

Add all features from the given (feature) map as document features. The map can have keys and values of any type, but when adding features, the following conversions are carried out: null keys are removed, any key that is not a String is converted to String. The value of all features should be something that is directly JSON-serialisable, but this is not checked. Note that some types can get serialised to JSON but will get converted to a different type when read back from JSON! The user is responsible for making sure that value types work with the JSON default serialisation. If a feature has already been added previously, its old value is replaced.

Parameters:

fm - a map to interpret as a feature map

Returns:

modified BdocDocumentBuilder

setText

public BdocDocumentBuilder setText(String text)

Set/update the text of the document.

Parameters:

text - the new document text

Returns:

modified BdocDocumentBuilder

setName

public BdocDocumentBuilder setName(String name)

Set/update the name of the bdoc document.

Parameters:

name - the new document name

Returns:

modified BdocDocumentBuilder

setAnnotationSetNames

public BdocDocumentBuilder setAnnotationSetNames(Collection<String> names)

Set the list of included AnnotationSet names. This allows you to select the annotation sets to actually use from a GATE document. If set names are specified which are not in initial or currently known list of sets, this is silently ignored. That way the same selection can be used for many documents, even if some of them do not actually contain some of the sets.

Parameters:

names - a collection of names to choose and use for the BdocDocument

Returns:

modified BdocDocumentBuilder

setIncludePlaceholderSets

public BdocDocumentBuilder setIncludePlaceholderSets(boolean flag)

Set if placeholders sets should get included. This is only relevant if a subset of all annotation sets is selected to get added.

Parameters:

flag -

Returns:

setFeatureNames

public BdocDocumentBuilder setFeatureNames(Collection<String> featurenames)

Set the list of included features. This allows you to select the features to actually use from a GATE document. If features are selected which are not known, this is silently ignored.

Parameters:

featurenames - a collection of feature names to choose and use for the BdocDocument

Returns:

modified BdocDocumentBuilder

addFeature

public BdocDocumentBuilder addFeature(String name,
                                      Object value)

Add/set a single feature as a document feature.

Parameters:

name - Feature name

value - Feature value

Returns:

modified BdocDocumentBuilder

javaOffsets

public BdocDocumentBuilder javaOffsets()

Make the JsonDocument use java offsets (the default).

Returns:

modified BdocDocumentBuilder

pythonOffsets

public BdocDocumentBuilder pythonOffsets()

Make the JsonDocument use python/unicode codepoint offsets. This wil fix all the annotation offsets so they refer to unicode code points instead of java utf16 code units. This will only work if the text of the json document is set and compatible with the offsets of the added annotations, otherwise an exception is thrown.

Returns:

modified BdocDocumentBuilder

buildBdoc

public BdocDocument buildBdoc()

Given all the info accumulated, build a JsonDocument and return it. This adds a BdocDocument instance with all the information added so far.

Returns:

the BdocDocument containing all the information added so far

toJson

public void toJson(File path)

Store the BdocDocument to a file.

Parameters:

path - where to store

toJson

public void toJson(String path)

Store the BdocDocument to a file.

Parameters:

path - where to store

toJsonString

public String toJsonString()

Convert the BdocDocument to a JSON string.

Returns:

JSON String

toJson

public void toJson(OutputStream os)

Write the BdocDocument to the output stream.

Parameters:

os - stream to write to