Class: DataSetUtil

josm/ds. DataSetUtil

DataSetUtil provides methods to build OSM primitive IDs and to manipulate data in a DataSet.

new DataSetUtil( [ds])

Build an utility object wrapping the dataset ds

Creates an instance of DataSetUtil for a given DataSet
Parameters:
Name Type Argument Description
ds DataSet <optional>
the dataset. Creates a new dataset if missing
Source:
Example
import { DataSetUtil, DataSet } from 'josm/ds'
const dsutil = new DataSetUtil(new DataSet())

Members


<readonly> nodeBuilder

Replies a node builder to create Nodes in this dataset.
Properties:
Name Type Description
nodeBuilder module:josm/builder~NodeBuilder
Source:
Example
import { DataSet, DataSetUtil } from 'josm/ds'
const dsutil = new DataSetUtil(new DataSet())
const n = dsutil.nodeBuilder
   .withId(1234,4567)
   .withTags({amenity: 'restaurant'})
   .create()
dsutil.has(n)

<readonly> relationBuilder

Replies a relation builder to create relations in this dataset.
Properties:
Name Type Description
relationBuilder module:josm/builder~RelationBuilder
Source:
Example
import { DataSet, DataSetUtil } from 'josm/ds'

const dsutil = new DataSetUtil(new DataSet())
const r = dsutil.relationBuilder()
   .withId(8765,1234)
   .create({tags: {type: 'network'}})
ds.has(r)  // --> true

<readonly> wayBuilder

Replies a way builder to create ways in this dataset.
Properties:
Name Type Description
wayBuilder module:josm/builder~WayBuilder
Source:
Example
import { DataSet, DataSetUtil } from 'josm/ds'

const dsutil = new DataSetUtil(new DataSet())
const nb = dsutil.nodeBuilder()
const w = dsutil.wayBuilder()
  .withNodes(nb.create(), nb.create())
  .create(1234, {tags: {highway: "residential"}})
dsutil.has(w)

Methods


<static> load(source [, options])

Loads a dataset from a file.

Derives the format of the file from the file suffix, unless the named option options.format is set.

options can contain the following named options:

format
one of the strings osm (Open Street Map XML data), osc (Open Street Map change format), or osm.gz (Open Street Map XML data, compressed with gzip). The format is normalized: white space is removed and it is converted to lower case.
Parameters:
Name Type Argument Description
source string | File the data source
options object <optional>
optional named parameters
Source:
Returns:
the data set util with the loaded data set
Type
module:josm/ds~DataSetUtil
Example
import { DataSetUtil } from 'josm/ds'

// loads an OSM file
DataSetUtil.load('/path/to/my/file.osm')

// loads an OSM file, explicity passing in the format
DataSetUtil.load('/path/to/my/file.any-suffix', { format 'osm' })

batch(delegate)

Run a sequence of operations against the dataset in "batch mode". Listeners to data set events are only notified at the end of the batch.
Parameters:
Name Type Description
delegate function the function implementing the batch process. Ignored if null or undefined.
Source:
Example
import { DataSet, DataSetUtil } from 'josm/ds'
const dsutil = new DataSetUtil(new DataSet())
// creates and adds two nodes and a way in batch operation
// to the dataset
dsutil.batch(() => {
   const n1 = dsutil.nodeBuilder().create()
   const n2 = dsutil.nodeBuilder().create()
   dsutil.wayBuilder().withNodes(n1,n2).create()
})

get(args)

Replies an OSM object from the dataset, or undefined, if no such object exists. Signatures
get(id, type)
Replies an object given by its unique numeric id and a type. The type is either a string "node", "way", or "relation", or one of the symbols OsmPrimitiveType.NODE, OsmPrimitiveType.WAY, or OsmPrimitiveType.RELATION.
get(id)
Replies an object given an ID. id is either an instance of PrimitiveId or an object with the properties id and type, i.e. {id: 1234, type: "node"}.
Parameters:
Name Type Description
args see description
Source:
Example
import { buildId , DataSetUtil, DataSet, OsmPrimitiveType} from 'josm/ds'

const dsutil = new DataSetUtil(new DataSet())
// get a node
const n1  = dsutil.get(1234, 'node')

// get a way
const w1 =  dsutil.get(3333, OsmPrimitiveType.WAY)

// get a relation
const r1 = dsutil.get({id: 5423, type: 'relation'})

// pass in a SimplePrimitiveId
const id = buildId(-5, OsmPrimitiveType.NODE)
const n2 = dsutil.get(id)

// pass in a primitive to get it
const w2 = dsutil.wayBuilder().create(987)
const w3 = dsutil.get(w2)

node(id)

Replies the node with id id, or null.
Parameters:
Name Type Description
id number the unique numeric id. Must not be 0.
Source:
Returns:
the node
Type
Node
Example
import { DataSet, DataSetUtil } from 'josm/ds'

const dsutil = new DataSetUtil(new DataSet())
// get a node
const n = dsutil.node(1234)

query(expression [, options])

Queries the dataset

Signatures

query(josmSearchExpression,?options)
Queries the dataset using the JOSM search expression josmSearchExpression. josmSearchExpression is a string as you would enter it in the JOSM search dialog. options is an (optional) object with named parameters, see below.
query(predicate,?options)
Queries the dataset using a javascript predicate function predicate. predicate is a javascript function which accepts a object as parameter and replies true, when it matches for the object ans false otherwise. options is an (optional) object with named parameters, see below.
The parameter options consist of the following (optional) named parameters:
allElements : boolean (Deprecated parameter names: all)
If true, searches all objects in the dataset. If false, ignores incomplete or deleted objects. Default: false.
caseSensitive : boolean
Only applicable for searches with a JOSM search expression. If true, searches case sensitive. If false, searches case insensitive. Default: false.
regexSearch : boolean (Deprecated parameter names: withRegexp, regexpSearch)
Only applicable for searches with a JOSM search expression. If true, the search expression contains regular expressions. If false, it includes only plain strings for searching. Default: false.
mapCSSSearch
Only applies for searches with a JOSM search expression. Default: false.
Parameters:
Name Type Argument Description
expression string | function the match expression
options object <optional>
additional named parameters
Source:
Example
import { DataSetUtil } from 'josm/ds'
const dsutil = new DataSetUtil()
// add or load primitives to query
// ...

// query restaurants
const result1 = dsutil.query('amenity=restaurant')

// query all nodes with a type query
const result2 = dsutil.query('type:node')

// query using a custom predicate - all primitives
// with exactly two tags
const result3 = dsutil.query((primitive) => {
  primitive.getKeys().size() === 2
})

relation(id)

Replies the relation with id id.
Parameters:
Name Type Description
id number the unique numeric id. Must not be 0.
Source:
Returns:
the relation
Type
Relation
Example
import { DataSet, DataSetUtil } from 'josm/ds'

const dsutil = new DataSetUtil(new DataSet())
// get a relation
const r  = dsutil.relation(1234)

remove(args)

Removes objects from the dataset Signatures
remove(id, type)
Removes a single object given by its unique numeric ID (nid) and a type. The type is either a string "node", "way", or "relation", or one of the symbols OsmPrimitiveType.NODE, OsmPrimitiveType.WAY, or OsmPrimitiveType.RELATION.
remove(id, id, ...)
Removes a collection of objects given by the ids. id is either an instance of PrimitiveId or an object with the properties id and type, i.e. {id: 1234, type: "node"}. null and undefined are ignored.
remove(array|collection)
Removes a collection of objects given by the an array or a java.util.Collection of ids. The collection elemeents are either instances of PrimitiveId or an object with the properties id and type, i.e. {id: 1234, type: "node"}. null or undefined elements are ignored.
Parameters:
Name Type Description
args see description
Source:
Example
import { DataSet, DataSetUtil, OsmPrimitiveType, buildId} from 'josm/ds'
const HashSet = Java.type('java.util.HashSet')
const dsutil = new DataSetUtil(new DataSet())

// remove a node with a global id
dsutil.remove(1234, 'node')

// remove a node and a way
const id1 = buildId(1234, 'node')
const id2 = buildId(3333, OsmPrimitiveType.WAY)
dsutil.remove(id1, id2)

// remove a relation and a node
dsutil.remove({id: 1234, type: 'relation'}, id1)

// remove an array of nodes
dsutil.remove([id1,id2])

// remove a set of primitives
const ids = new HashSet()
ids.add(id1)
ids.add(id1)
dsutil.remove(ids)

save(target [, options])

Saves the dataset to a file (in OSM XML format).

options can contain the following named options:

version: string
the value of the attribute version in the OSM file header. Default: "0.6"
changeset: Changeset
the changeset whose id is included in the attribute changeset on every OSM object. If undefined, includes the individual changeset attribute of the OSM object. Default: undefined
osmConform: bool
if true, prevents modification attributes to be written Default: true
Parameters:
Name Type Argument Description
target string | File the target file
options object <optional>
optional named parameters
Source:
Example
import { DataSetUtil } from 'josm/ds'

const dsutil = new DataSetUtil()
// create a node in the dataset
dsutil.nodeBuilder()
 .withId(1, 1)
 .withPosition({ lat: 1.0, lon: 1.0 })
 .create()

// save the dataset
dsutil.save('/tmp/my-dataset.osm')

way(id)

Replies the way with id id, or null
Parameters:
Name Type Description
id number the unique numeric id. Must not be 0.
Source:
Returns:
the way
Type
Way
Example
import { DataSet, DataSetUtil } from 'josm/ds'

const dsutil = new DataSetUtil(new DataSet())
// get a way
const w  = dsutil.way(1234)