Niagara provides a uniform naming system to identify any resource
which may be represented using an instance of BObject
.
These names are called ords for Object Resolution
Descriptor. You can think of a ords as URIs on steroids.
An ord is a list of one or more queries separated by the "|" pipe symbol. Each query is an ASCII string formatted as "<scheme>:<body>". The scheme name is a globally unique identifier which instructs Niagara how to find a piece of code to lookup an object from the body string. The body string is opaque and is formatted differently depending on the scheme. The only rule is that it can't contain a pipe symbol.
Queries can be piped together to let each scheme focus on how to
lookup a specific type of object. In general absolute ords are of
the format: host | session | space
. Some examples:
ip:somehost|fox:|file:/dir/somefile.txt ip:somehost|fox:1912|station:|slot:/Graphics/Home local:|module://icons/x16/cut.png
In the examples above note that the "ip" scheme is used to identify a host machine using an IP address. The "fox" scheme specifies a session to that machine usually on a specific IP port number. In the first example we identify an instance of a file within somehost's file system. In the second example we identify a specific component in the station database.
The third example illustrates a special case. The scheme "local"
which always resolves to BLocalHost.INSTANCE
is both
a host scheme and a session scheme. It represents objects found
within the local VM.
The core naming APIs are defined in the
javax.baja.naming
package. Ords are represented using the
BOrd
class.
Ords may be resolved using the BOrd.resolve()
or
BOrd.get()
methods. The resolve
method
returns an intermediate OrdTarget
that provides
contextual information about how the ord was resolved. The get
method is a convenience for resolve().get()
.
Ords may be absolute or relative. When resolving a relative ord
you must pass in a base object. If no base object is specified
then BLocalHost.INSTANCE
is assumed. Some simple
examples of resolving an ord:
BIFile f1 = (BIFile)BOrd.make("module://icons/x16/cut.png").get();
BIFile f2 = (BIFile)BOrd.make("file:somefile.txt").get(baseDir);
Ords may be parsed into their constituent queries using the
method BOrd.parse()
which returns OrdQuery[]
.
In many cases you might cast a OrdQuery into a concrete class. For
example:
// dump the names in the file path
BOrd ord = BOrd.make("file:/a/b/c.txt");
OrdQuery[] queries = ord.parse();
FilePath path = (FilePath)queries[0];
for(int i=0; i<path.depth(); ++i)
System.out.println("path[" + i + "] = " + path.nameAt(i));
The following is an informal introduction some common ord schemes used in Niagara.
The "ip" scheme is used to identify a BIpHost
instance.
Ords starting with "ip" are always absolute and ignore any base
which may be specified. The body of a "ip" query is a DNS hostname
or an IP address of the format "dd.dd.dd.dd".
The "fox" scheme is used to establish a Fox session. Fox is the primary protocol used by Niagara for IP communication. A "fox" query is formatted as "fox:" or "fox:<port>". If port is unspecified then the default 1911 port is assumed.
The "file" scheme is used to identify files on the file system. All
file ords resolve to instances of
javax.baja.file.BIFile
.
File queries always parse into a FilePath
File ords come in the following flavors:
Sys absolute paths indicate files rooted under the Niagara
installation directory identified via Sys.getBajaHome()
.
User absolute paths are rooted under the user home directory
identified via Sys.getUserHome()
. In the case of
station VMs, user home is the directory of the station database.
The "module" scheme is used to access BIFiles
inside
the module jar files. The module scheme uses the "file:" scheme's
formating where the authority name is the module name. Module
queries can be relative also. If the query is local absolute then
it is assumed to be relative to the current module. Module queries
always parse into a FilePath
module://icons/x16/file.png module://baja/javax/baja/sys/BObject.bajadoc module:/doc/index.html
The "station" scheme is used to resolve the BComponentSpace
of a station database.
The "slot" scheme is used to resolve a BValue
within
a BComplex
by walking down a path of slot names. Slot
queries always parse into a SlotPath
.
The "h" scheme is used to resolve a BComponent
by
its handle. Handles are unique String identifiers for BComponents
within a BComponentSpace
. Handles provide a way to
persistently identify a component independent of any renames which
modify a component's slot path.
The "service" scheme is used to resolve a BComponent
by
its service type. The body of the query should be a type spec.
The "spy" scheme is used to navigate spy pages. The
javax.baja.spy
APIs provide a framework for making diagnostics information easily
available.
The "bql" scheme is used to encapsulate a BQL query.
Copyright © 2000-2019 Tridium Inc. All rights reserved.