JOSM Scripting Plugin - JavaScript API V3

Class: WayBuilder

josm/builder/way~ WayBuilder

new WayBuilder( [ds])

Helps to create OSM Ways

WayBuilder helps to create OSM Ways. Methods of WayBuilder can be used in a static and in an instance context. It isn't necessary to create an instance of WayBuilder, unless it is configured with a DataSet, to which created ways are added.
Parameters:
Name Type Argument Description
ds DataSet <optional>
 a JOSM dataset to which created ways are added. If missing, the created ways aren't added to a dataset.
Source:
Example
import {WayBuilder} from 'josm/builder'
 const DataSet = Java.type('org.openstreetmap.josm.data.osm.DataSet')

 const ds = new DataSet()
 // create a way builder without and underlying dataset ...
 let wbuilder = new WayBuilder()
 // ... with an underlying dataset ....
 wbuilder =  new WayBuilder(ds)
 // ... or using this factory method
 wbuilder = WayBuilder.forDataSet(ds)


 // create a new local way
 const w1 = wbuilder.create()

 // create a new global way
 const w2 = wbuilder.withTags({highway: 'residential'}).create(1111)

 // create a new proxy for a global way
 // (an 'incomplete' node in JOSM terminology)
 const w3 = wbuilder.createProxy(2222)

Classes

WayBuilder
Creates a new WayBuilder with an underlying dataset.

Methods

create( [id] [, options])

Creates a new way. Can be used in an instance or in a static context.
Parameters:
Name Type Argument Description
id number <optional>
 a global way id. If missing and not set before using withId(..), creates a new local id.
options module:josm/builder/way~WayBuilder.WayBuilderOptions <optional>
 additional parameters for creating the way
Source:
Returns:
the created way
Type
Way
Example
import {WayBuilder, NodeBuilder} from 'josm/builder'
// create a new local way
const w1 = WayBuilder.create()

// create a new global way
const w2 = WayBuilder.create(1111)

// create a new global way with version 3 with some nodes and with
// some tags
const w3 = WayBuilder.create(2222, {
  version: 3,
  tags: {higway: 'primary'},
  nodes: [
    NodeBuilder.withPosition(1,1).create(),
    NodeBuilder.withPosition(2,2).create(),
    NodeBuilder.withPosition(3,3).create()
  ]
})

createProxy(id)

Creates a new proxy way. A proxy way is a way for which we only know its global id. In order to know more details (nodes, tags, etc.), we would have to download it from the OSM server. The method can be used in a static and in an instance context.
Parameters:
Name Type Description
id number the id. A number > 0
Source:
Returns:
the new proxy way
Type
Way
Example
import {WayBuilder} from 'josm/builder'

// a new proxy way for the global way with id 1111
const w1 = WayBuilder.createProxy(1111)

forDataSet(ds)

Creates or configures a WayBuilder which will add created nodes to the dataset ds.
Parameters:
Name Type Description
ds DataSet the dataset to which created objects are added
Source:
Returns:
the way builder
Type
module:josm/builder/way~WayBuilder
Example
import {DataSet, WayBuilder} from 'josm/builder'

// create a new way builder which builds to a data set
const ds = new DataSet()
let wb = WayBuilder.forDataSet(ds)

withId(id [, version])

Declares the global way id and the global way version. The method can be used in a static and in an instance context.
Parameters:
Name Type Argument Description
id number (mandatory) the global way id. A number > 0.
version number <optional>
 the global way version. If present, a number > 0. If missing, the version 1 is assumed.
Source:
Returns:
the way builder (for method chaining)
Type
module:josm/builder/way~WayBuilder
Example
import {WayBuilder} from 'josm/builder'
// creates a global way with id 1111 an version 22
const way = WayBuilder.withId(1111, 22).create()

withNodes( [nodes])

Declares the nodes of the way. Accepts either a vararg list of Node, an array of Nodes or a Java list of Nodes. At least two non-identical nodes have to be supplied. The same node can occure more than once in the list, but a consecutive sequence of the same node is collapsed to one node. The method can be used in a static and in an instance context.
Parameters:
Name Type Argument Description
nodes Node | List | Node[] <optional>
 the list of nodes. See description and examples.
Source:
Returns:
the way builder (for method chaining)
Type
module:josm/builder/way~WayBuilder
Example
import {WayBuilder, NodeBuilder} from 'josm/builder'
// creates a new local way with two local nodes
const way = WayBuilder.withNodes(
  NodeBuilder.create(), 
  NodeBuilder.create()
).create()

withTags( [tags])

Declares the tags to be assigned to the new way. The method can be used in a static and in an instance context.
Parameters:
Name Type Argument Description
tags object <optional>
 the tags
Source:
Returns:
the way builder (for method chaining)
Type
module:josm/builder/way~WayBuilder
Example
import {WayBuilder} from 'josm/builder'
// a new global way with the global id 1111 and tags name='Laubeggstrasse'
// and highway=residential
const w1 = WayBuilder.withTags({name:'Laubeggstrasse', highway:'residential'})
    .create(1111)

// a new local way with tags name=test and highway=road
const tags = {
    name    : 'Laubeggstrasse',
    highway : 'residential'
}
const w2 = WayBuilder.withTags(tags).create()

Type Definitions

WayBuilderOptions

Named options for {@link module:josm/builder/way~WayBuilder#create create}
Properties:
Name Type Argument Default Description
id number <optional>
 the id (> 0) of the way. Default: creates new local id.
version number <optional>
 1 the version (> 0) of the way. Default: 1.
tags object <optional>
 an object with tags. Null values and undefined values are ignored. Any other value is converted to a string. Leading and trailing white space in keys is removed.
nodes Node[] | List <optional>
 the nodes for the way.
Source:
Example
import {NodeBuilder} from 'josm/builder'
// options to create a way
const options = {
  version: 3,
  tags: {highway: 'primary'},
  nodes: [
    NodeBuilder.withPosition(1,1).create(),
    NodeBuilder.withPosition(2,2).create(),
    NodeBuilder.withPosition(3,3).create()
  ]
}