bajaScript Class: Ord

new Ord()

Object Resolution Descriptor.

An ORD is how we can access Objects in the Server from BajaScript. It's
similar to a URI but is much more powerful and extensible. For more
information, please see the Niagara developer documentation on ORDs and how
they're used.

If more than one ORD needs to be resolved then use a baja.BatchResolve.

This Constructor shouldn't be invoked directly. Please use the make()
methods to create an instance of an ORD.

See:

Example

Resolve an ORD

baja.Ord.make("station:|slot:/Folder/NumericWritable").get({ lease: true })
    .then(function (numericWritable) {
      baja.outln(numericWritable.getOutDisplay());
    });

Extends

baja.Simple

Members

<static> DEFAULT :baja.Ord

Default ORD instance.

Type:

baja.Ord

Methods

<static> make(ord)

Make an ORD.

The argument can be a String, Ord or an Object.

If an Object is passed in then if there's a base and child property,
this will be used to construct the ORD (by calling toString on each).
Otherwise toString will be called on the Object for the ORD.

Parameters:

Name	Type	Description
`ord`	String \| baja.Ord \| Object

Returns:

Type: baja.Ord

Example

Resolve an ORD

baja.Ord.make("station:|slot:/Folder/NumericWritable").get({ lease: true })
    .then(function (numericWritable) {
      baja.outln(numericWritable.getOutDisplay());
    });

<static> replaceBackups(ord)

Slot and file path ord queries may contain "../" to do relative traversal up the tree. If
there is more than one backup, the ord will contain "/../", which will be replaced by the
browser within a URL by removing other sections. For example, https://127.0.0.1/a/b/c/d/../e/f
is converted to https://127.0.0.1/a/b/c/e/f and https://127.0.0.1/a/b/c/d/../../e/f is
converted to https://127.0.0.1/a/b/c/f. This will result in unintended behavior in subsequent
ord resolution with that URL. Therefore, all but the last "../" is replaced with {@code
":..|"}. This function replicates the behavior of BOrdUtil#replaceBackups.

Parameters:

Name	Type	Description
`ord`	baja.Ord	ord that is searched for "../" backups

Since:

Niagara 4.3U1

Returns:

the original ord if no changes are necessary or an updated ord with the
necessary replacements

Type: baja.Ord

decodeAsync(str [, batch])

The string encoding of certain Simples may include Type information, or
other data that may be require asynchronous operations to decode. BOX is
designed to handle these situations when decoding data from the station,
but when user code needs to decode string-encoded Simples directly, prefer
this method as it gives the individual Simple a chance to import Types,
etc. to ensure that the decoded Simple is fully correct.

The default implementation just returns decodeFromString directly.

Parameters:

Name	Type	Argument	Description
`str`	string
`batch`	baja.comm.Batch	<optional>	optional batch to use

Inherited From:

baja.Simple#decodeAsync

Returns:

may return the Simple instance
directly, or a Promise resolving to same - so wrap in Promise.resolve()
if unsure.

Type: baja.Simple | Promise.<baja.Simple>

decodeFromString(str)

Decode an ORD from a String.

Parameters:

Name	Type	Description
`str`	String	the ORD String.

Overrides:

baja.Simple#decodeFromString

Returns:

the decoded ORD.

Type: baja.Ord

encodeToString()

Encode an ORD to a String.

Overrides:

baja.Simple#encodeToString

Returns:

the ORD encoded to a String.

Type: String

equals(obj)

Equality test.

Parameters:

Name	Type	Description
`obj`

Inherited From:

baja.Simple#equals

Returns:

Type: Boolean

equivalent(obj)

Equivalence test.

equivalent() is used to compare if two Objects have equivalent
state, but might not want to return true for equals since it
it has implied semantics for many operations. The default
implementation returns the result of baja.Object#equals.

Parameters:

Name	Type	Description
`obj`

Inherited From:

baja.Object#equivalent

Returns:

Type: Boolean

get( [obj])

Resolve the ORD and get the resolved Object from the ORD Target.

This method calls baja.Ord#resolve and calls get on the ORD
Target to pass the object onto the ok function callback.

For more information on how to use this method please see
baja.Ord#resolve.

Parameters:

Name	Type	Argument	Description
`obj`	Object	<optional>

See:

module:baja/ord/OrdTarget#resolve

Returns:

a promise that will be resolved with the value specified
by the ORD.

Type: Promise

Example

Resolve/get an ORD

baja.Ord.make("service:baja:UserService|slot:jack").get({ lease: true })
    .then(function (user) {
      baja.outln(user.get('fullName'));
    })
    .catch(function (err) {
      baja.error('ORD failed to resolve: ' + err);
    });

getAgents( [is] [, batch])

Returns a promise that resolves to the agent list for this Object.

Parameters:

Name	Type	Argument	Description
`is`	Array.<String>	<optional>	An optional array of filters to add to the agent query.
`batch`	baja.comm.Batch	<optional>	An optional object used to batch network calls together.

Inherited From:

baja.Object#getAgents

See:

baja.registry.getAgents

Returns:

A promise that will resolve with the Agent Info.

Type: Promise

getDataTypeSymbol()

Return the data type symbol.

Returns:

the Symbol used for encoding this data type (primarily
used for facets).

Type: String

getIcon()

Return the Object's Icon.

Inherited From:

baja.Object#getIcon

Returns:

Type: baja.Icon

getType()

Get the type of this instance.

Inherited From:

baja.Object#getType

Returns:

Type: Type

getTypeDisplayName( [cx])

Gets the friendly type display name for this object.

Parameters:

Name	Type	Argument	Description
`cx`	Object	<optional>	a context to be passed down to Type

Since:

Niagara 4.10

Inherited From:

baja.Object#getTypeDisplayName

See:

baja.Type#getDisplayName

Returns:

If no context is provided, the type
display name is returned synchronously as a string. If context provided,
the type display name is resolved via a promise as a string.

Type: Promise.<string> | string

getVariables()

Since:

Niagara 4.10

Throws:

if a variable name is invalid or empty, or if a variable declaration is malformed
Type Error

Returns:

an array of all variable names present in this ORD

Type: Array.<string>

hasVariables()

Since:

Niagara 4.10

Throws:

if a variable name is invalid or empty, or if a variable declaration is malformed
Type Error

Returns:

true if this ORD has any variables present

Type: boolean

isNull()

Since:

Niagara 4.10

Returns:

if this represents the null ORD.

Type: boolean

make(ord)

Make an ORD.

Parameters:

Name	Type	Description
`ord`	String \| baja.Ord \| Object

Overrides:

baja.Simple#make

See:

baja.Ord.make

Returns:

Type: baja.Ord

newCopy( [exact])

Every value may be cloned using the newCopy method.

Please note that Simples are immutable so they don't
allocate a new instance.

Parameters:

Name	Type	Argument	Description
`exact`	Boolean	<optional>	true if an exact copy of the value should be made (only valid in the Component architecture).

Inherited From:

baja.Value#newCopy

See:

baja.Simple

Returns:

a copy of the value (or the same instance if the value is a
Simple).

normalize()

Return a normalized version of the ORD.

Returns:

Type: baja.Ord

parse()

Parse an ORD to a number of ORD Query objects.

Returns:

a list of ORDs to resolve.

Type: baja.OrdQueryList

relativizeToSession()

Relativize is used to extract the relative portion
of this ord within an session:

First the ord is normalized.
Starting from the left to right, if any queries are
found which return true for isSession(), then remove
everything from that query to the left.

See:

baja.OrdQuery#isSession

Returns:

Type: baja.Ord

resolve( [obj])

Resolve an ORD.

Resolving an ORD consists of parsing and processing it to get a result.
The result is an ORD Target.

Any network calls that result from processing an ORD are always
asynchronous.

The resolve method requires an ok function callback or an object
literal that contains the method's arguments.

Please note that unlike other methods that require network calls, no
batch object can be specified!

Parameters:

Name Type Argument Description

obj

Object

the object literal that contains the method's
arguments.

Properties

Name	Type	Argument	Description
`ok`	function	<optional>	(Deprecated: use Promise) the ok function called once the ORD has been successfully resolved. The ORD Target is passed to this function when invoked.
`fail`	function	<optional>	(Deprecated: use Promise) the fail function called if the ORD fails to resolve. An error cause is passed to this function when invoked.
`base`		<optional>	the base Object to resolve the ORD against.
`lease`	Boolean	<optional>	if defined and true, any Components are temporarily subscribed.
`leaseTime`	Number \| baja.RelTime	<optional>	the amount of time in milliseconds to lease for (`lease` argument must be true). As well as a Number, this can also be a baja.RelTime. If undefined, BajaScript's default lease time will be used.
`subscriber`	baja.Subscriber	<optional>	if defined the `Component` is subscribed using this `Subscriber`.
`cursor`	Object	<optional>	if defined, this specifies parameters for iterating through a Cursor (providing the ORD resolves to a Collection or Table). For more information, please see baja.coll.tableMixIn.cursor.

See:

Returns:

a promise that will be resolved with an
OrdTarget when the ORD has been resolved.

Type: Promise.<Object>

Example

Resolve an ORD

baja.Ord.make("station:|slot:/").resolve({
    lease: true // ensure any resolved Components are leased
  })
    .then(function (target) {
      // process the ORD Target
    })
    .catch(function (err) {
      // ORD failed to resolve
    });

substitute(variables)