Interface TR069Connector
-
public interface TR069Connector
A TR-069 Connector is an assistant to a TR-069 Protocol Adapter developer. The connector manages the low level details of converting the different TR-069 RPCs to a Device Management Tree managed by Dmt Admin. The connector manages the conversions from the TR-069 Object Names to a node in the DMT and vice versa.The connector uses a Dmt Session from the caller, which is given when the connector is created. The connector does not implement the exact RPCs but only provides the basic functions to set and get the parameters of an object as well as adding and deleting an object in a table. A TR-069 developer must still parse the XML, handle the relative and absolute path issues, open a Dmt Session etc.
The connector assumes that each parameter or object path is relative to the root of the Dmt Session.
This connector must convert the TR-069 paths to Dmt Admin URIs. This conversion must take into account the
LIST
andMAP
concepts defined in the specifications as well as the synthetic parametersNumberOfEntries
andAlias
. These concepts define the use of anInstanceId
node that must be used by the connector to provide a TR-069 table view on theLIST
andMAP
nodes.
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
PREFIX
The MIME type prefix.static int
TR069_BASE64
Constant representing the TR-069 base64 type.static int
TR069_BOOLEAN
Constant representing the TR-069 boolean type.static int
TR069_DATETIME
Constant representing the TR-069 date time type.static int
TR069_DEFAULT
Constant representing the default or unknown type.static int
TR069_HEXBINARY
Constant representing the TR-069 hex binary type.static int
TR069_INT
Constant representing the TR-069 integer type.static int
TR069_LONG
Constant representing the TR-069 long type.static java.lang.String
TR069_MIME_BASE64
Constant representing the TR-069 base64 type.static java.lang.String
TR069_MIME_BOOLEAN
Constant representing the TR-069 boolean type.static java.lang.String
TR069_MIME_DATETIME
Constant representing the TR-069 date time type.static java.lang.String
TR069_MIME_DEFAULT
Constant representing the default or unknown type.static java.lang.String
TR069_MIME_EAGER
Constant representing the TR-069 eager type.static java.lang.String
TR069_MIME_HEXBINARY
Constant representing the TR-069 hex binary type.static java.lang.String
TR069_MIME_INT
Constant representing the TR-069 integer type.static java.lang.String
TR069_MIME_LONG
Constant representing the TR-069 long type.static java.lang.String
TR069_MIME_STRING
Constant representing the TR-069 string type.static java.lang.String
TR069_MIME_STRING_LIST
Constant representing the TR-069 string list type.static java.lang.String
TR069_MIME_UNSIGNED_INT
Constant representing the TR-069 unsigned integer type.static java.lang.String
TR069_MIME_UNSIGNED_LONG
Constant representing the TR-069 unsigned long type.static int
TR069_STRING
Constant representing the TR-069 string type.static int
TR069_UNSIGNED_INT
Constant representing the TR-069 unsigned integer type.static int
TR069_UNSIGNED_LONG
Constant representing the TR-069 unsigned long type.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description java.lang.String
addObject(java.lang.String path)
Add a new node to the Dmt Admin as defined by the AddObject RPC.void
close()
Close this connector.void
deleteObject(java.lang.String objectPath)
Delete an object from a table.java.util.Collection<ParameterInfo>
getParameterNames(java.lang.String objectOrTablePath, boolean nextLevel)
Getting theParameterInfo
objects addressed by path.ParameterValue
getParameterValue(java.lang.String parameterPath)
Getting a parameter value.void
setParameterValue(java.lang.String parameterPath, java.lang.String value, int type)
Setting a parameter.java.lang.String
toPath(java.lang.String uri)
Convert a Dmt Session relative Dmt Admin URI to a valid TR-069 path, either a table, object, or parameter path depending on the structure of the DMT.java.lang.String
toURI(java.lang.String name, boolean create)
Convert a TR-069 path to a Dmt Session relative Dmt Admin URI.
-
-
-
Field Detail
-
PREFIX
static final java.lang.String PREFIX
The MIME type prefix.- See Also:
- Constant Field Values
-
TR069_MIME_DEFAULT
static final java.lang.String TR069_MIME_DEFAULT
Constant representing the default or unknown type. If this type is used a default conversion will take place- See Also:
- Constant Field Values
-
TR069_MIME_INT
static final java.lang.String TR069_MIME_INT
Constant representing the TR-069 integer type.- See Also:
- Constant Field Values
-
TR069_MIME_UNSIGNED_INT
static final java.lang.String TR069_MIME_UNSIGNED_INT
Constant representing the TR-069 unsigned integer type.- See Also:
- Constant Field Values
-
TR069_MIME_LONG
static final java.lang.String TR069_MIME_LONG
Constant representing the TR-069 long type.- See Also:
- Constant Field Values
-
TR069_MIME_UNSIGNED_LONG
static final java.lang.String TR069_MIME_UNSIGNED_LONG
Constant representing the TR-069 unsigned long type.- See Also:
- Constant Field Values
-
TR069_MIME_STRING
static final java.lang.String TR069_MIME_STRING
Constant representing the TR-069 string type.- See Also:
- Constant Field Values
-
TR069_MIME_STRING_LIST
static final java.lang.String TR069_MIME_STRING_LIST
Constant representing the TR-069 string list type.- See Also:
- Constant Field Values
-
TR069_MIME_BOOLEAN
static final java.lang.String TR069_MIME_BOOLEAN
Constant representing the TR-069 boolean type.- See Also:
- Constant Field Values
-
TR069_MIME_BASE64
static final java.lang.String TR069_MIME_BASE64
Constant representing the TR-069 base64 type.- See Also:
- Constant Field Values
-
TR069_MIME_HEXBINARY
static final java.lang.String TR069_MIME_HEXBINARY
Constant representing the TR-069 hex binary type.- See Also:
- Constant Field Values
-
TR069_MIME_DATETIME
static final java.lang.String TR069_MIME_DATETIME
Constant representing the TR-069 date time type.- See Also:
- Constant Field Values
-
TR069_MIME_EAGER
static final java.lang.String TR069_MIME_EAGER
Constant representing the TR-069 eager type.- See Also:
- Constant Field Values
-
TR069_DEFAULT
static final int TR069_DEFAULT
Constant representing the default or unknown type. If this type is used a default conversion will take place- See Also:
- Constant Field Values
-
TR069_INT
static final int TR069_INT
Constant representing the TR-069 integer type.- See Also:
- Constant Field Values
-
TR069_UNSIGNED_INT
static final int TR069_UNSIGNED_INT
Constant representing the TR-069 unsigned integer type.- See Also:
- Constant Field Values
-
TR069_LONG
static final int TR069_LONG
Constant representing the TR-069 long type.- See Also:
- Constant Field Values
-
TR069_UNSIGNED_LONG
static final int TR069_UNSIGNED_LONG
Constant representing the TR-069 unsigned long type.- See Also:
- Constant Field Values
-
TR069_STRING
static final int TR069_STRING
Constant representing the TR-069 string type.- See Also:
- Constant Field Values
-
TR069_BOOLEAN
static final int TR069_BOOLEAN
Constant representing the TR-069 boolean type.- See Also:
- Constant Field Values
-
TR069_BASE64
static final int TR069_BASE64
Constant representing the TR-069 base64 type.- See Also:
- Constant Field Values
-
TR069_HEXBINARY
static final int TR069_HEXBINARY
Constant representing the TR-069 hex binary type.- See Also:
- Constant Field Values
-
TR069_DATETIME
static final int TR069_DATETIME
Constant representing the TR-069 date time type.- See Also:
- Constant Field Values
-
-
Method Detail
-
setParameterValue
void setParameterValue(java.lang.String parameterPath, java.lang.String value, int type) throws TR069Exception
Setting a parameter. This method should be used to provide the SetParameterValues RPC. This method must convert the parameter Name to a URI and replace the DMT node at that place. It must follow the type conversions as described in the specification.The connector must attempt to create any missing nodes along the way, creating parent nodes on demand.
If the value of a an Alias node is set then the parent node must be renamed. For example, if the value of
M/X/Alias
is set toY
then the node will have a URI ofM/Y/Alias
. The value must not be escaped as the connector will escape it.- Parameters:
parameterPath
- The parameter pathvalue
- A trimmed string value that has the given type. The value can be in either canonical or lexical representation by TR069.type
- The type of the parameter (TR069_INT
,TR069_UNSIGNED_INT
,TR069_LONG
,TR069_UNSIGNED_LONG
,TR069_STRING
,TR069_DATETIME
,TR069_BASE64
,TR069_HEXBINARY
,TR069_BOOLEAN
)- Throws:
TR069Exception
- The following fault codes are defined for this method: 9001, 9002, 9003, 9004, 9005, 9006, 9007, 9008.- 9001
TR069Exception.REQUEST_DENIED
- 9002
TR069Exception.INTERNAL_ERROR
- 9003
TR069Exception.INVALID_ARGUMENTS
- 9004
TR069Exception.RESOURCES_EXCEEDED
- 9005
TR069Exception.INVALID_PARAMETER_NAME
- 9006
TR069Exception.INVALID_PARAMETER_TYPE
- 9007
TR069Exception.INVALID_PARAMETER_VALUE
- 9008
TR069Exception.NON_WRITABLE_PARAMETER
- 9001
-
getParameterValue
ParameterValue getParameterValue(java.lang.String parameterPath) throws TR069Exception
Getting a parameter value. This method should be used to implement the GetParameterValues RPC. This method does not handle retrieving multiple values as the corresponding RPC can request with an object or table path, this method only accepts a parameter path. Retrieving multiple values can be achieved with thegetParameterNames(String, boolean)
.If the
parameterPath
ends inNumberOfEntries
then the method must synthesize the value. TheparameterPath
then has a pattern like(object-path)(table-name)NumberOfEntries
. The returned value must be anTR069_UNSIGNED_INT
that contains the number of child nodes in the table(object-path)(table-name)
. For example, ifA.B.CNumberOfEntries
is requested the return value must be the number of child nodes underA/B/C
.If the value of a an
Alias
node is requested then the name of the parent node must be returned. For example, if the path isM.X.Alias
then the returned value must beX
.The connector must attempt to create any missing nodes along the way, creating parent nodes on demand.
- Parameters:
parameterPath
- A parameter path (must refer to a valid parameter, not an object or table).- Returns:
- The name, value, and type triad of the requested parameter as
defined by the TR-069
ParameterValueStruct
. - Throws:
TR069Exception
- The following fault codes are defined for this method: 9001, 9002, 9003, 9004, 9005.
-
getParameterNames
java.util.Collection<ParameterInfo> getParameterNames(java.lang.String objectOrTablePath, boolean nextLevel) throws TR069Exception
Getting theParameterInfo
objects addressed by path. This method is intended to be used to implement the GetParameterNames RPC.The connector must attempt to create any missing nodes that are needed for the
objectOrTablePath
by using thetoURI(String, boolean)
method withtrue
.This method must traverse the sub-tree addressed by the path and return the paths to all the objects, tables, and parameters in that tree. If the nextLevel argument is
true
then only the children object, table, and parameter information must be returned.The returned
ParameterInfo
objects must be usable to discover the sub-tree.If the child nodes have an
InstanceId
node then the returned names must include theInstanceId
values instead of the node names.If the parent node is a
MAP
, then the syntheticAlias
parameter must be included.Any
MAP
andLIST
node must include aParameterInfo
for the correspondingNumberOfEntries
parameter.- Parameters:
objectOrTablePath
- A path to an object or table.nextLevel
- Iftrue
consider only the children of the object or table addressed bypath
, otherwise include the whole sub-tree, including the addressed object or table.- Returns:
- A collection of
ParameterInfo
objects representing the resulting child parameter, objects, and tables as defined by the TR-069ParameterInfoStruct
. - Throws:
TR069Exception
- If the fault is caused by an invalid ParameterPath value, the Invalid Parameter Name fault code (9005) MUST be used instead of the more general Invalid Arguments fault code (9003). A ParameterPath value must be considered invalid if it is not an empty string and does not exactly match a parameter or object name currently present in the data model. IfnextLevel
istrue
andobjectOrTablePath
is a parameter path rather than an object/table path, the method must return a fault response with the Invalid Arguments fault code (9003). If the value cannot be gotten for some reason, this method can generate the following fault codes::
-
addObject
java.lang.String addObject(java.lang.String path) throws TR069Exception
Add a new node to the Dmt Admin as defined by the AddObject RPC. The path must map to either aLIST
orMAP
node as no other nodes can accept new children.If the path ends in an alias (
[ ALIAS ]
) then the node name must be the alias, however, no new node must be created. Otherwise, the Connector must calculate a unique instance id for the new node name that follows the TR-069 rules for instance ids. That is, this id must not be reused and must not be in use. That is, the id must be reserved persistently.If the
LIST
orMAP
node has a Meta Node with a MIME type application/x-tr-069-eager then the node must be immediately created. Otherwise no new node must be created, this node must be created when the node is accessed in a subsequent RPC.The alias name or instance id must be returned as identifier for the ACS.
- Parameters:
path
- A table path with an optional alias at the end- Returns:
- The name of the new node.
- Throws:
TR069Exception
- The following fault codes are defined for this method: 9001, 9002, 9003, 9004, 9005. If an AddObject request would result in exceeding the maximum number of such objects supported by the CPE, the CPE MUST return a fault response with the Resources Exceeded (9004) fault code.
-
deleteObject
void deleteObject(java.lang.String objectPath) throws TR069Exception
Delete an object from a table. A missing node must be ignored.- Parameters:
objectPath
- The path to an object in a table to be deleted.- Throws:
TR069Exception
- The following fault codes are defined for this method: 9001, 9002, 9003, 9005. If the fault is caused by an invalid objectPath value, the Invalid Parameter Name fault code (9005) must be used instead of the more general Invalid Arguments fault code (9003). A missing node forobjectPath
must be ignored.
-
toPath
java.lang.String toPath(java.lang.String uri) throws TR069Exception
Convert a Dmt Session relative Dmt Admin URI to a valid TR-069 path, either a table, object, or parameter path depending on the structure of the DMT. The translation takes into account the special meaningLIST
,MAP
,Alias
, andInstanceId
nodes.- Parameters:
uri
- A Dmt Session relative URI- Returns:
- An object, table, or parameter path
- Throws:
TR069Exception
- If there is an error
-
toURI
java.lang.String toURI(java.lang.String name, boolean create) throws TR069Exception
Convert a TR-069 path to a Dmt Session relative Dmt Admin URI. The translation takes into account the special meaningLIST
,MAP
,InstanceId
node semantics.The synthetic
Alias
orNumberOfEntries
parameter cannot be mapped and must throw anTR069Exception.INVALID_PARAMETER_NAME
.The returned path is properly escaped for TR-069.
The mapping from the path to a URI requires support from the meta data in the DMT, it is not possible to use a mapping solely based on string replacements. The translation takes into account the semantics of the MAP and LIST nodes. If at a certain point a node under a
MAP
node does not exist then the Connector can create it if thecreate
flag is set totrue
. Otherwise a non-existent node will terminate the mapping.- Parameters:
name
- A TR-069 pathcreate
- Iftrue
, create missing nodes when they reside under a MAP or LIST- Returns:
- A relative Dmt Admin URI
- Throws:
TR069Exception
- If there is an error
-
close
void close()
Close this connector. This will not close the corresponding session.
-
-