A TR-069 Protocol Adapter first creates a Dmt Session on the node in the DMT that maps to an object model that should be visible to the TR-069 Management Server. A Protocol Adapter can choose to map a whole sub-tree or it can create a virtual object model based on different nodes, this depends on the implementation of the Protocol Adapter.

When a TR-069 RPC arrives, the Protocol Adapter must parse the SOAP message and analyze the request. In general, an RPC can request the update or retrieval of multiple values. The Protocol Adapter must decompose these separate requests into single requests and execute them as a single unit. If the request is a retrieval or update of a data model maintained in the Dmt Admin service then the Protocol Adapter can use a TR069 Connector to simplify implementing this request. The TR069 Connector Factory service can be used to create an instance of a TR069 Connector that is based on a specific Dmt Session.

The TR069 Connector maps the Object or Parameter Name to a URI and perform the requested operation on the corresponding node. The name-to-URI conversion supports the LIST and MAP concepts as defined in OSGi Object Modeling.

The TR069 Connector handles conversion from the Dmt Admin data types to the TR-069 data types. There is a default mapping for the standard Dmt Admin formats including the comma separated list supported by TR-069. However, Data Plugins that implement TR-069 aware object models can instruct the TR069 Connector by providing specific MIME types on the Meta Node.

Objects can be added and deleted but are, in general, not added immediately. These objects are lazily created when they are accessed. The reason is that TR-069 does not support the concept of a session with atomic semantics, a fact leveraged by certain object models in the DMT. Therefore, adding an object will assign a instance id to an object but the creation of the object is delayed until the object is used.

After all the requests in an RPC are properly handled the TR069 Connector must be closed, the Dmt Session must be closed separately.

Errors are reported to the caller as they happen, if a Dmt Admin service error is fatal then the Dmt Session will be closed and it will be necessary to create a new TR069 Connector.

[1] TR-069 Amendment 3 is a technical report (Broadband Forum's specification model) that specifies a management protocol based on [4] SOAP 1.1 over HTTP. The TR-069 technical report defines a number of mandatory Remote Procedure Calls (RPCs) that allow a management system, the Auto-Configuration Server (ACS), to discover the capabilities of the Consumer Premises Equipment (CPE) and do basic management. This model is depicted in Figure 131.2.

Figure 131.2 TR-069 Reference Architecture

In TR-069, the CPE is always initiating the conversation with the ACS though the ACS can request a session.

Inside the CPE there is a Protocol Adapter that implements the TR-069 RPCs. These RPCs read and modify the objects models present in the CPE. There is usually a mechanism that allows the different modules in the CPE to contribute a management object to the Protocol Adapter so that the Protocol Adapter does not require knowledge about highly specialized domains.

[2] TR-106 Amendment 3 specifies object model guidelines to be followed by all TR-069-enabled devices as well as a formal model to document these object models.

The object model of TR-069 consists of objects that contain parameters as well as tables that contain objects. TR-106 says:

Figure 131.3 Type Model TR-069

Objects can also occur in tables, in that case the object name is suffixed with an instance id. An object that has no instance id is a singleton, with an instance id they are referred to as tables. In the Broadband Forum technical reports tables end in the special suffix {i}, the instance id.

This provides the following structural definition for this specification:

named-value ::= NAME ( object | table | parameter )
object      ::= named-value +
table       ::= ( instance object )*
parameter   ::=
instance    ::= INTEGER > 0

TR-069 talks about partial paths and parameter names. In this specification, a name is reserved for the short relative name used inside an object, also called the local name. The term path is reserved for the combination of object names, table names, and instance ids that are separated by a full stop ('.' \u002E) and used to traverse an instance model.

path           ::= parameter-path | object-path| table-path
segment        ::= NAME '.' ( instance '.' )?
object-path    ::= segment+
table-path     ::= segment* NAME '.'   // expect INTEGER next
parameter-path ::= object-path NAME
instance-path  ::= table-path instance '.'

In this specification the following terms are used consistently:

This provides a hierarchy as depicted in Figure 131.4.

Figure 131.4 TR-069 Object and Parameter naming relative to the parameter MemoryStatus

The grammars for parameter names and object names are as follows:

NAME ::= ( Letter | '_' )
         ( Letter | Digit | '-' | '_' | CombiningChar| Extender )*

The productions Letter, Digit, CombiningChar, and Extender are defined in [5] Extensible Markup Language (XML) 1.0 (Second Edition). The name basically supports the full Unicode character set for letters and digits (including digits for other languages), including sets for languages like Hebrew and Chinese. Examples of different parameter names are:

name            // simple name
Name            // case sensitive
_                           
_-_-_
ångstrom            
þingsten
ΨΣΩΠ

A parameter value can have one of the data types defined in [2] TR-106 Amendment 3, they are summarized in Table 131.1.

SOAP messages always provide a type for the parameter value. For example:

<ParameterValueStruct>
  <name>Parameter1</name>
  <value xsi:type="long">1234</value>
</ParameterValueStruct>

The xsi prefix refers to the http://www.w3.org/2001/XMLSchema-instance namespace. However, this makes not all TR-106 types well defined, for example in XML Schema base64 is called base64Binary. This specification assumes that the names and definitions in Table 131.1 and provides appropriate constants for the Protocol Adapter.

Parameters can be read-only or read-write. All writable Parameters must also be readable although security can cause certain parameters to be read as an empty string, for example passwords. Parameters can reflect configuration as well as status of the device. External causes can cause parameters to change at any time. The TR-069 protocol has the facility to call an Inform RPC to provide the ACS with a notification of changed parameters.

Parameter attributes provide the meta data for a parameter. In TR-069, the attributes are used to manage notifications and access control. Each parameter in TR-069 can be watched by the ACS by setting the corresponding parameter attribute to active or passive notifications. Passive notifications are passed whenever the CPE communicates with the ACS and active notifications initiate a session. Parameters that have a notification are said to be watched.

Access to the parameters can be managed by setting Access Control Lists via the corresponding parameter attribute.

TR-106 has the concept of an object stored in a table to allow multiple instances of the same type. It is part of the object definition if it is stored in a table or not. An object cannot both appear as a table instance and as a singleton.

Each instance in the table is addressed with an integer >= 1. This instance id is not chosen by the ACS since it can be required to create a new instance due to an external event. For example the user plugging in a USB device or starting a new VOIP session. The ACS must discover these instance ids by asking the device for the instance ids in a table.

For example, the parameter path Device.LAN.DHCPOption.4.Request refers to a parameter on a DHCPOption object that has the instance id 4. Instance ids are not sequential nor predictable. It is the responsibility of the device to choose an instance id when an object is created. Instance ids are assumed to be persistent so that the ACS can cache results from a discovery process.

Newer TR-069 objects have been given an Alias parameter. This alias uniquely identifies the table instance.

TR-069 defines a convention for a parameter that contains the number of entries in a table. Any parameter name that ends with NumberOfEntries contains the number of entries in a table with the name of the prefix in the same object. For example A.B.CNumberOfEntries provides the number of entries in the table:

A.B.C.

The object model implemented in a device is accessed and modified with RPCs. RPCs are remote procedure calls; a way to invoke a function remotely. TR-069 defines a number of mandatory RPCs and provides a mechanism to extend and discover the set of RPCs implemented by a CPE. The mandatory RPCs are listed in in the following table.

The security model of TR-069 is based around the authentication taking place during the setup of a TLS (formerly SSL) connection. This authentication is then used to manage the access control lists via the parameter attributes.

A session with the ACS is always initiated by the CPE. The ACS can request a session, but it is always the CPE that starts a session by opening the connection to the ACS and then sending an Inform RPC. The session ends when the connection is closed, which happens after the ACS has informed the CPE it has no more requests.

During a session, a CPE has the requirements that parameters must not change due to other sources than the session and that the parameters are consistent with the changes. However, there is no transactionality over the session, atomicity is only guaranteed for one RPC. An RPC can consist of multiple parameter modifications that should therefore be atomically applied.

TR-069 sessions always start with an Inform RPC from the CPE to the ACS. This RPC contains any events and notifications for parameters that were watched. Events signal crucial state changes from the CPE to the ACS. For example, if a device has rebooted it will inform the ACS. Notifications are caused by parameter changes, the Inform RPC contains a list of events and parameters with changed values.

Invoked RPCs can return a fault status if errors occur during the execution of the RPC. For ACS to CPE RPCs these fault codes start at 9000, for the reverse direction they start at 8000. Each RPC defines the fault codes that can occur and their semantics in that context.

Developers implementing the TR-069 protocol are not likely to be also experts in the Dmt Admin service. This specification therefore provides a TR069 Connector Factory service that provides an object that can map from the TR-069 concepts to the Dmt Admin concepts, supporting all the constructs defined in the OSGi Object Modeling.

The TR069 Connector only specifies a number of primitive functions to manage the DMT. Parsing the SOAP messages, handling the notifications, and splitting the requests for TR069 Connector is the responsibility of the Protocol Adapter. The reason that the TR069 Connector does not work on a higher level is that a Protocol Adapter for TR-069 will likely communicate with other subsystems in the CPE than the OSGi framework alone. Though the Dmt Plugin model is an attractive approach to implement object models, there is history. Existing code will likely not be rewritten just because it can be done better as a Data Plugin.

For example, a Data Plugin could implement the Device.DeviceInfo. object. However, this object actually resides in the DMT at a node:

./TR-069/Device/DeviceInfo

A TR-069 Protocol Adapter will therefore be confronted with a number of data models that reside in different places. Each place provides one or more consistent data models but it is the responsibility of the TR-069 Protocol Adapter to ensure the ACS gets a consistent and standardized view of the whole. To create this consistent view it will be necessary to adapt the paths given in the RPCs. It is expected that a Protocol Adapter is required to have a certain amount of domain knowledge, for example a table, that maps TR-069 paths to their actual providers.

The basic model is depicted in Figure 131.5.

Figure 131.5 TR-069 Connector Context

The Protocol Adapter can be implemented as an OSGi Bundle or it can be implemented in native code in the device. Both architectures are viable. For certain aspects like the TR-157a3 Software Modules a certain amount of native code will be required to manage the OSGi Framework as an Execution Environment.

In an environment where the Protocol Adapter is implemented outside an OSGi Framework it will be necessary to create a link to the Dmt Admin service. This can be achieved with a proxy bundle inside the OSGi framework that dispatches any requests from the native Protocol Adapter to the functionality present in the OSGi Framework. In this specification, it is assumed that such proxies can be present. However, the examples are all assuming that the Protocol Adapter is running as a Bundle.

A TR069 Connector is associated with a Dmt Session, the TR069ConnectorFactory provides the create(DmtSession) method that will return a TR069Connector object. This object remains associated with the Dmt Session until the Dmt Session is closed, which can happen because of a fatal error or when the TR069 Connector Factory is unregistered or un-gotten/released. Creating a TR069 Connector must not be expensive, Protocol Adapters should create and close them at will. Closing the connector must not close the corresponding Dmt Session.

The TR069 Connector must use the root of the session as its base. That is, their URI mapping all parameters must start from the base. For example, if the session is opened at ./TR-069 then the parameter IGD/DeviceInfo/Manufacturer must map to URI ./TR-069/IGD/DeviceInfo/Manufacturer.

If a Protocol Adapter will modify the tree then it should use an atomic session for all RPCs even if the RPC indicates read-only. The reason for the atomicity is that in certain cases the lazy behavior of the TR069 Connector requires the creation of objects during a read operation. If a non-atomic session is used then the TR069 Connector must not attempt to lazily create objects and reject any addObject(String) and deleteObject(String) methods. See also Lazy and Sessions.

The TR069 Connector supports a limited number of RPCs, and for those RPCs it only supports the singleton case. The TR069 Connector provides support for the RPCs primitives listed in the following table.

An object or parameter path describes a traversal through a set of objects, this is almost the same model that Dmt Admin provides. The difference is that the characters allowed in a TR-069 parameter name are different from the Dmt Admin node names and that TR-069 does not support application specific parameter/object names like the Dmt Admin service does.

A path consist of a number segments, where each segment identifies a name or instance id. TR-069 names can always be mapped to Dmt Admin node names as the character set of TR-069 parameter names is restricted and falls within the character set of the Dmt Admin node names. The length of a segment could be a problem but TR-069 paths are generally limited to have a length of less than 256 bytes. This specification therefore assumes that a segment of a TR-069 path is never too long to fit in a Dmt Admin node name.

Mapping a Dmt Admin node name to a parameter name, needed for browsing, is more complicated as Dmt Admin node names allow virtually every Unicode character except the solidus ('/' \u002F). It is therefore necessary to escape Dmt Admin URIs into a path that is acceptable for the TR-069 protocol. It is assumed that escaping is only used in a browsing mode since native object models will never require escaping. The TR069 Connector must return names from the getParameterNames(String,boolean) call that the ACS can handle, optionally show to the user, and then use to construct new paths for subsequent RPCs.

There is no obvious escape character defined in TR-069, like for example the reverse solidus ('\' \u005C) that the Dmt Admin uses for escaping. The character for escaping is the latin small letter thorn ('þ' \u00FE) because his character is highly unlikely to ever be used in a TR-069 path for a native object model, however, even if it is then it would be no problem for the escaping algorithm. The thorn is a letter, allowing it to be used as the first character in a parameter name, this allows escaping the first character.

A character in a segment that is not allowed must be escaped into the following sequence:

þ[0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z]

The 4 hexadecimal upper case digits form a hexadecimal number that is the Unicode for that character. Each character that does not conform to the syntax specified in Parameter Names or the thorn character itself must be replaced with the escape sequence. For example, the name 3ABCþ must be translated to:

þ0033ABCþ00FE

If the segment is an instance id then the segment must not be escaped. Otherwise, if the segment does not start with a Letter or underscore, then the first character must be escaped with the thorn.

Unescaping must undo the escaping. Any sequence of þ[0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z] must be replaced with the character with the corresponding Unicode. A thorn found without the subsequent 4 hexadecimal upper case digits must be treated as a single thorn. For readability it is best to minimize the escaping. However, any name given to the TR069 Connector that is escaped must be properly interpreted even if the unescaped string did not require escaping. For example, þ0031þ0032þ0033 must be usable as an object instance id as the unescaped form is 123, which is a number.

A number of examples of the escaping are shown in the following table.

The TR069 Connector only accepts escaped paths and returns escaped paths. When a method returns a path it must be properly escaped and suitable as a TR-069 path.

In general, the TR-069 Protocol Adapter is free to choose what parts of the DMT it wants to expose. A simple mapping table containing path prefixes can be used to define the handler for the given data model. However, since the intention is to allow TR-069 object models to be implemented in Dmt Admin Data Plugins there is a need to know where those plugins should reside in the DMT. This root is defined as:

./TR-069

Any Data Plugin that wants to provide an object model in the TR-069 family of object models should provide a Data Plugin rooted at the TR-069 root. For example, a Data Plugin implementing the InternetGatewayDevice.DeviceInfo. object should register its Data Plugin under the data Root URI ./TR-069/ InternetGatewayDevice/DeviceInfo

A path must be mapped from the TR-069 hierarchy to the Dmt Admin nodes URI. The Protocol Adapter decides the base in the DMT by opening the Dmt Session with a session root parameter. The TR-069 Connector must then traverse the tree from this base based on the TR-069 path. The Protocol Adapter must use the Instance Id for MAP and LIST nodes to traverse the DMT.

Assume that the URI of a node is requested for a given path P. The path P must be traversed from the root node. The root node can find the child, the first segment in P, and then use the same routine recursively for the remainder. This recursive routine must perform the following actions on each current node:

Since each node that is traversed this way knows the node name it corresponds to it is easy to create an encoded URI for Dmt Admin.

For example, the TR-069 path:

Device.DeviceInfo.Interface.14.Connections.3.BytesSent

Assuming that Interface node is a MAP node and its children have an InstanceId node, where the WAN_1 node has an InstanceId of 14.

The Connections node is a LIST and the children have no InstanceId, therefore the name is the index. The translated URI then looks like:

Device/DeviceInfo/Interface/WAN_1/Connections/3/BytesSent

The toURI(String,boolean) method can take a TR-069 path and perform the substitutions. If the create parameter is true then the TR069 Connector will create missing nodes if possible. Missing nodes can only be created under a LIST or MAP node.

A missing node is a node that is addressed by a path but not present in the DMT. For example, the root of the session is ./TR-069 and the parameter path is A.B.C. If the DMT contains ./TR-069/A but not ./TR-069/A/B then node B is a missing node.

The Protocol Adapter must synthesize an Alias parameter and for any MAP or LIST node called X it must provide a sibling XNumberOfEntries parameter that provides the number of entries in table X.

131.3.7.1 Alias

The Alias node is a read-write parameter that must map to the actual node name of its parent. For example, ./A/B/C/Alias must map to C. Reading it must provide the this parent's node name and writing it must rename this parent's node name. The Alias must be automatically provided on any child of a MAP node. The Alias parameter must also be returned in the result of getParameterNames(String,boolean) if its parent's children are included. It is not possible to convert an Alias parameter name to a URI as the Alias node is synthetic and does not exist in the DMT. The model of aliases are depicted in Figure 131.6.

Figure 131.6 Aliases

Aliases can be used by the ACS to set the key of a MAP. For example, if a set of properties is defined as a MAP:

Name	Act	Type	Card.	S	Description
Properties	Get	MAP	1	P	A Properties map
[string]	Get Set Add Del	string	0..n	A	Key/Value

An ACS can first add an object to the table. This will create an entry with a calculated instance id. However, the ACS can then rename the node with the Alias node. In pseudo code:

AddObject           ..Properties.               (returnsnode name = 3421)
SetParameterValue   ..Properties.3421.Alias = MyKey

Alternatively, addressing with an alias in the parameter name would be simpler:

AddObject           ..Properties.[MyKey]

In the Dmt Admin service the session plays an important role in how the object model operates. Especially atomic sessions have a clear point to commit any changes so that many actions can be deferred until all the information is available. In TR-069 there is no real session concept although one RPC must be executed atomically even if it changes multiple parameters. As there are different RPCs to create objects and set their parameters it is impossible to create and parameterize an object in a single session. This creates problems with general DMT models.

It is recommended to operate all RPCs in an atomic session to allow these DMT models to leverage the session commit phase. However, a TR-069 Connector must also accept a read only or exclusive session. The session can then of course cause exceptions to be thrown at certain operations.

The connector must lazily create instances. An addObject(String) method must not actually create the object, it only has to create an instance id and ensure the uniqueness of this id over time. The id must follow the rules from TR-069, it must not clash with an existing id even after such an id has been used in the past.

This id is then returned to the ACS who will then use it in subsequent RPCs. When one of the subsequent RPCs tries to access this not-yet existent node, for example a get or set, then the TR069 Connector must create it before it sets or gets the value of this node. This lazy strategy allows the node creation and the parameterization of that node to happen in a single session/RPC.

For example, in session 100 the addObject(String) creates a new node. This node is not really created but the unique instance id 4311 is assigned to it. After this RPC, the session is closed. The ACS receives this instance and then prepares a GetParameterValues RPC to get the ../4311/Foo parameter. The management agent receives the RPC and opens a new session 200, it then calls getParameterValue(String). The TR069 Connector will not find the appropriate entry 4311 in the table. Instead of raising an error it creates this node and then gets the value for the ../4311/Foo parameter.

A Data Plugin implementing a native TR-069 object model can override the lazy behavior by adding a application/x-tr-069-eager MIME type to the list of MIME types in the Meta Node. If this MIME type is present then the node must be eagerly created during the addObject(String) method.

The TR069 Connector must assign the unique id according to the TR-069 rules for instance ids.

This specifications assume the [2] TR-106 Amendment 3 defined data types. TR-106 defines a number of data types, derived from XML Schema and creates a number of sub-types to discriminate between different use cases. A Protocol Adapter must be able to understand the types defined in Table 131.5 to be able to faithfully define a data model based on [2] TR-106 Amendment 3. Discriminating between some of the sub-types requires inspection of the data. Each sub-type requires mapping rules that are defined later. Each mapping is assigned a unique MIME sub-type in the application media type. That is, the TR-069 int type has a MIME type of application/x-tr-069-int.

It is the responsibility of the Protocol Adapter to properly clean up the parameter values, that is, remove any unnecessary white space, etc. The TR069 Connector must accept any lexically correct form of the value of a parameter. However, the connector must always return the value according to the format of the data types specified by TR-069.

This section describes the conversion from a DMT node (a Dmt Data) to a TR-069 Parameter value. The source is the DMT node retrieved from the DMT. The destination is the value and its type that must be encoded in the TR-069 response. The meta node is the Meta Node associated with the source. This model is depicted in Figure 131.7.

Figure 131.7 DMT to TR-069

The different conversions possible for the Dmt Data to the TR-069 Parameter value are shown in Table 131.6. This table shows vertically the Dmt Admin formats and horizontally the TR-106 types defined in Table 131.5. Each row has a default conversion type, indicated with a bold entry. For example, the default conversion of a FORMAT_BOOLEAN to the boolean type is the default conversion.

This default conversion can be overridden by the Data Plugin by specifying an alternative MIME type in the list of allowed MIME types in the Meta Node getMimeTypes(). If this list contains a MIME type that has the prefix application/x-tr-069- then the first entry in this list must be chosen as the destination type instead of the default type. This way, a TR-069 Data Plugin can indicate the exact type to a TR-069 Protocol Adapter.

For example, a Dmt Data has the format FORMAT_BASE64. However, the Data Plugin for this node has a Meta Node that contains

String[] { "application/x-tr-069-hexBinary"}

The resulting type must therefore be hexBinary in this example.

The Dmt Data nodes are leaf nodes, however, there is a special case for interior LIST nodes marked with a application/x-tr-069-list type in the Meta Node. These nodes must be converted to a comma separated string as described in List.

Cells that are empty in the table indicate an impossible conversion that must be reported. Cells with a name refer to one of the subsequent sections.

A TR-069 Parameter value consists of a string and a type identifier from the set of TR-069 types, see Data Types. The conversion is depicted in Figure 131.7.

Figure 131.8 TR-069 to DMT

The destination type is obtained from the corresponding Meta Node. If multiple formats are specified in the result of the getFormat() method then the most applicable type must be used. The following table lists the applicability for each TR-106 data type.

base64        FORMAT_BASE64, FORMAT_BINARY, FORMAT_RAW_BINARY
boolean       FORMAT_BOOLEAN, FORMAT_STRING
dateTime      FORMAT_DATE_TIME, FORMAT_DATE, FORMAT_TIME
hexBinary     FORMAT_BASE64, FORMAT_BINARY, FORMAT_RAW_BINARY
int           FORMAT_INTEGER, FORMAT_LONG, FORMAT_FLOAT, FORMAT_STRING
long          FORMAT_LONG, FORMAT_FLOAT, FORMAT_INTEGER, FORMAT_STRING
string        FORMAT_STRING, FORMAT_BOOLEAN, FORMAT_INTEGER, FORMAT_LONG,
              FORMAT_FLOAT, FORMAT_RAW_STRING, FORMAT_XML
unsignedInt   FORMAT_INTEGER, FORMAT_LONG, FORMAT_FLOAT, FORMAT_STRING
unsignedLong  FORMAT_LONG, FORMAT_FLOAT, FORMAT_INTEGER, FORMAT_STRING

If the conversion fails and there are untried formats left then the other formats must be used.

There is a special case when the destination node is a LIST node with primitive children and the source is a string type. In that case the string must be parsed according to TR-106 comma separated lists and each element must be stored as a child node.

The conversion matrix is in the following table. The equal sign indicates identity taking into account any encoding. It is not necessary that the source type corresponds to a MIME type in the meta node.

The GetParameterValues RPC retrieves the value from one or more parameters. Each request in the RPC can request one parameter value or provides an object or table path, requesting multiple values with one path.

The getParameterValue(String) method retrieves the value of one parameter in the DMT. The getParameterNames(String,boolean) method can be used to retrieve the values of a table or object.

For the getParameterValue(String) method the TR069 Connector must first check for synthesized parameters, see Synthetic Nodes (Alias and NumberOfEntries). Otherwise, the parameter name must be converted to a URI, this must be done according to the toURI(String,boolean) method with the boolean set to true, creating any missing nodes if possible. The Dmt Data for this node must be converted according to DMT to TR-069 Conversion. The returned ParameterValue contains the type and value of the parameter.

For example:

ParameterValue v = connector.getParameterValue( 
          "Device.DeviceInfo.Manufacturer");
String value = v.getValue(); 
int type = v.getType();

The SetParameterValues RPC sets a number of values in one RPC. The setParameterValue(String,String,int) method corresponds to setting a single parameter in the DMT. It takes a parameter path, a value, and the type of this parameter.

The TR069 Connector must first check if the requested destination is the Alias node of a MAP child. If the Alias node is set, the name of the parent node must be renamed to the given value. The value of the Alias node must be a TR-069 string type, the Connector must ensure the value is escaped when necessary. See Synthetic Nodes for further information about aliases.

Otherwise, the parameter name must be converted to a URI, this must be done according to the toURI(String,boolean) method with the boolean set to true.

The given value must be converted to a Dmt Data according to the TR-069 to Dmt Data Conversion. For example:

connector.setParameterValue("Starwars.R2D.2.Start", 
                             "20110805T10:15:20Z", TR069_DATETIME );

The GetParameterNames RPC allows an ACS to discover the parameters accessible on a particular CPE as well as verifying the existence of a parameter. There are modes for this RPC depending on the path and next level arguments. See the following table.

The result must include only parameters, objects, and tables that are actually implemented by the CPE. If a parameter is listed then a getParameterValue(String) method called with this parameter's path should succeed. As a convenience, the ParameterInfo class provides a getParameterValue() method as a short cut to the value.

For example, assume the following instances:

IGD.LAN.1.Hosts.
IGD.LAN.1.Hosts.HostNumberOfEntries
IGD.LAN.1.Hosts.Host.
IGD.LAN.1.Hosts.Host.1.
IGD.LAN.1.Hosts.Host.1.Active
IGD.LAN.1.Hosts.Host.2.
IGD.LAN.1.Hosts.Host.2.Active
IGD.LAN.2.Hosts.
IGD.LAN.2.Hosts.HostNumberOfEntries

The following table demonstrates some of the different results based on these example instances.

For example:

Collection<ParameterInfo> pinfos = connector.getParameterNames("Device.");
for ( ParameterInfo info : pinfos ) {
  if ( info.isParameter() ) {
     System.out.println( 
         connector.getParameterValue(info.getName()).getValue());    
  }
}

The AddObject RPC creates a new instance in a table. There basic form for this RPC is to create an object and return the name of this object. It is also possible to specify an alias (a name specified in square brackets) after the table path. In that case, the alias is used as the node name. In either case, the path must be a valid table path pointing to a an existing MAP or LIST node.

When an object is added without an alias then the TR069 Connector must assign a unique id. TR-069 mandates that this id is unique for the table. The TR069 Connector must be able to create and maintain such a persistent id range. The Connector must ensure that any id chosen is not actually already in use or has been handed out recently. How such an id is calculated and maintained is implementation dependent.

If alias based addressing is used, a name between square brackets, then the alias is retrieved from the square brackets. The DMT must then be verified that no node exists in the corresponding table. If it does already exist, an INVALID_PARAMETER_NAME exception is thrown. Otherwise the alias is returned as the selected name.

If the corresponding MAP or LIST node has a Meta Node with a MIME type of application/x-tr-69-eager then the alias or instance id must be used to create the node. Otherwise the alias or instance id must be returned without creating the node. The purpose of this lazy creation is to allow a single Set Parameter Values RPC to atomically create a number of nodes and set their values.

For example:

String id = connector.addObject( "Starwars.CP.3.Obiwan.");
connector.setParameterValue( "Starwars.CP.3.Obiwan." + id+ ".Name", 
                                            "cp30", TR069_STRING );

The previous code gets an assigned id with the addObject(String) method. The setParameterValue(String,String,int) then assigns the string cp30 to the Name node. This will first create the actual node since it was not created in the addObject(String) method and then sets the value of the DMT Starwars/CP/3/Obiwan/<id>/Name node.

The addObject(String) method requires an atomic session. If a non-atomic session is used then the addObject(String) method must not attempt to create any objects and an exception must be thrown.

The DeleteObject RPC deletes an object from the tree, it takes the instance path as argument. This behavior is implemented in the deleteObject(String) method. The corresponding node must be deleted if it exists. No error must be raised if the node does not exist in the DMT.

For example, deleting the object created in Add Object:

connector.deleteObject("Starwars.CP.3.Obiwan.cp30.");