JOSM Scripting Plugin - JavaScript API V3

Class: RelationBuilder

josm/builder/relation~ RelationBuilder

new RelationBuilder(ds)

Helps to create Relations

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

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

// create a new local relation
const r1 = rbuilder.create()

// create a new global way
const r2 = rbuilder.withTags({route: 'bicycle'}).create(1111)

// create a new proxy for a global relation
// (an 'incomplete' node in JOSM terminology)
const r3 = rbuilder.createProxy(2222)

Methods

<static> forDataSet(ds)

Creates or configures a RelationBuilder which will add created nodes to the dataset ds.
Parameters:
Name Type Description
ds DataSet a JOSM dataset which created ways are added to.
Source:
Returns:
the relation builder
Type
module:josm/builder/relation~RelationBuilder
Example
import {RelationBuilder} = 'josm/builder'

// create a new relation builder building to a data set
const DataSet = Java.type('org.openstreetmap.josm.data.osm.DataSet')
const ds = new DataSet()
const rb1 = RelationBuilder.forDataSet(ds)

// configure an existing relation builder
let rb2 = new RelationBuilder()
rb2 = rb2.forDataSet(ds)

<static> member( [role], primitive)

Utility function - creates a relation member

Create a RelationMember
member(role, obj)
Create a relation member with role role and member object obj. role can be null or undefined, obj must neither be null nor undefinde. role is a string, obj is an OSM node, a way, or a relation.
member(obj)
Create a relation member for the member object obj. obj must neither be null nor undefinde. obj is an OSM node, a way, or a relation. The created relation member has no role.
Parameters:
Name Type Argument Description
role string <optional>
 the member role
primitive primitive the member primitive
Source:
Returns:
the relation member
Type
RelationMember
Example
import {RelationBuilder, NodeBuilder} from 'josm/builder'

// create a new RelationMember with role 'house' for a new node
const m1 = RelationBuilder.member('house', NodeBuilder.create())
// create a new RelationMember with an empty role for a new node
const m2 = RelationBuilder.member(NodeBuilder.create())

create( [id] [, options])

Creates a new relation. 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/relation~RelationBuilder.RelationBuilderOptions <optional>
 options for creating the relation
Source:
Returns:
the relation
Type
Relation
Example
import { NodeBuilder, RelationBuilder } from 'josm/builder'
const member = RelationBuilder.member
// create a new local relation
const r1 = RelationBuilder.create()

// create a new global relation
const r2 = RelationBuilder.create(1111)

// create a new global relation with version 3 with some tags and two
// members
const r3 = RelationBuilder.create(2222, {
   version: 3,
   tags: {type: 'route'},
   members: [
       member('house', NodeBuilder.create()),
       member(NodeBuilder.create())
   ]
 })

createProxy(id)

Creates a new proxy relation. A proxy relation is a relation, for which we only know its global id. In order to know more details (members, 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 for the proxy relation
Source:
Returns:
the new proxy relation
Type
Relation
Example
import {RelationBuilder} from 'josm/builder'

// a new proxy relation for the global way with id 1111
const r1 = RelationBuilder.createProxy(1111)

withId(id [, version])

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

withMembers(members)

Declares the members of a relation. Accepts either a vararg list of relation members, nodes, ways or relations, an array of relation members, nodes ways or relations, or a Java list of members, nodes, ways or relation. The method can be used in a static and in an instance context.
Parameters:
Name Type Argument Description
members OsmPrimitive | RelationMember | Array.<(OsmPrimitive|RelationMember)> | List <repeatable>
 the list of members. See description and examples.
Source:
Returns:
the relation builder (for method chaining)
Type
module:josm/builder/relation~RelationBuilder
Example
import {RelationBuilder, NodeBuilder} from 'josm/builder'
const {member} = RelationBuilder
const r1 = RelationBuilder.withMembers(
    member('house', NodeBuilder.create()),
    member('house', NodeBuilder.create())
  )
  .create()

const members = [
  NodeBuilder.create(),  // empty role
  member('house', NodeBuilder.create()
]

const r2 = RelationBuilder.withMembers(
   members, 
   NodeBuilder.create(),
).create()

withTags( [tags])

Declares the tags to be assigned to the new relation. 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:
a relation builder (for method chaining)
Type
module:josm/builder/relation~RelationBuilder
Example
import {RelationBuilder} from 'josm/builder'
// a new global relation with the global id 1111 and tags route='bicycle'
//and name='n8'
const r1 = RelationBuilder.withTags({name:'n8', route:'bicycle'}).create(1111)

// a new local relation with tags name=test and highway=road
const tags = {
     name  : 'n8',
     route : 'bicycle'
}
const r2 = RelationBuilder.withTags(tags).create()

Type Definitions

RelationBuilderOptions

Named options for {@link module:josm/builder/relation~RelationBuilder#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.
members RelationMember[] | List <optional>
 the member for the relation
Source:
Example
import {RelationBuilder, NodeBuilder} from 'josm/builder'
const {member} = RelationBuilder
// options to create a relation
const options = {
  version: 3,
  tags: {type: 'route'},
  members: [
    member('house', NodeBuilder.create()),
    member(NodeBuilder.create())
  ]
}