Updating an Existing Component

Note – This section builds on concepts discussed in Section 6.7.1.

A component definition does not have a version number. Each time an existing component needs to be updated, a new component with the same name (based on the previous component definition) is defined in a new version of the document. Generally the new version of the document is an amendment.

Import the previous version of the component. This is done using an import/- component element (see Section 6.3.3). Note that the imported component is referred to locally by a different name (usually the local name is the same as the remote name but is prefixed with an underscore).

If the amended document also needs to update a model, then import the previous version

of the model using an import/model element (see Section 6.3.2).

Note: Broadband Forum standard Data Models no longer define both components and models within the same DM Instance.

Define a new “diffs” component that will only contain the changes needed to extend the imported component. This is done using a component definition element (I.6), discussed in Section 6.7.1. The convention is to name this component as the concatenation of the imported component name and the text “Diffs”. The name should not be prefixed with an underscore. This is because names that begin with underscores are local and cannot be imported by other files; but the Diffs component has to be importable.

Redefine the original component (using a component definition element; I.6) as a union of the imported component and the “diffs” component (using component reference elements; I.7). This is actually a new component defined within the local document, which has the same name as the remotely defined component.

If the amended document needs to update a model, then reference (include) the “diffs” component from within the updated model using the model/component element (I.7).

Note: Broadband Forum standard Data Models no longer define both components and models within the same DM Instance.

The following example demonstrates this process, where the imported component is defined in the previous version of the same document. This example builds on the UserInterface example from Section 6.7.1.

<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" ... spec="urn:broadband-forum-org:tr-181-2-2-0">

...

<import file="tr-181-2-1.xml" spec="urn:broadband-forum-org:tr-181-2-1"> ...

<component name="_UserInterface" ref="UserInterface"/> <model name="Device:2.1"/>

</import>

<component name="UserInterfaceDiffs">

<object base="UserInterface." access="readOnly" minEntries="1" maxEntries="1"> <parameter base="PasswordReset" access="readWrite">

<syntax command="true"> <boolean/> </syntax> </parameter> </object> </component> <component name="UserInterface"> <component ref="_UserInterface"/> <component ref="UserInterfaceDiffs"/> </component>

<model name="Device:2.2" base="Device:2.1">

<component path="Device." ref="UserInterfaceDiffs"/> ...

</model> </dm:document>

In the above example, the imported component is defined remotely as UserInterface and is referred to locally as _UserInterface. The updates needed to extend the imported component are defined solely within the new UserInterfaceDiffs component. The UserInterface component is then redefined within the local document as the union of the _UserInterface and UserInterfaceDiffs components. This means that the new UserInterface component contains the full definition (i.e. previous version plus changes).

Note that the above example also revises the associated model (defines Device:2.2 based on the previous Device:2.1), in order to incorporate the component updates within the model. Since the revised model only needs the changes, the model/component element simply references the “diffs” component.

Separate documents:

It is also possible and recommended that the component to be updated, and the model in which it is included, are defined in different documents. The basic process in updating and including the component is the same as discussed above, but the work is split across both documents.

The following listings demonstrate this process; the updated component is defined in tr-157-1-3

and the updated model is defined in tr-181-2-123. This example builds on the NSLookupDiag

example from Section 6.7.2.

<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" ... spec="urn:broadband-forum-org:tr-157-1-3-0">

...

<import file="tr-157-1-2.xml" spec="urn:broadband-forum-org:tr-157-1-2"> ...

<component name="_NSLookupDiag" ref="NSLookupDiag"/> ... </import> ... <component name="NSLookupDiagDiffs"> <object base="NSLookupDiagnostics.Result.{i}." ...> <parameter base="Status" ...> <description action="replace">

Result Parameter representing whether NS Lookup was successful... </description> </parameter> </object> </component> <component name="NSLookupDiag"> <component ref="_NSLookupDiag"/> <component ref="NSLookupDiagDiffs"/> </component> ... </dm:document> <dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" ... spec="urn:broadband-forum-org:tr-181-2-1-0"> ... 23

Note that tr-157-1-3 defines its own models, which also reference NSLookupDiagDiffs, but these have been omitted from this example since the concept is already covered in the previous example.

<import file="tr-157-1-3.xml" spec="urn:broadband-forum-org:tr-157-1-3"> ... <component name="NSLookupDiagDiffs"/> ... </import> ...

<model name="Device:2.1" base="Device:2.0"> ...

<component path="Device.DNS.Diagnostics." ref="NSLookupDiagDiffs"/> ...

</model> </dm:document>

In the above tr-157-1-3 document listing, the NSLookupDiag component import, the definition of the “diffs” component, and the redefinition of the imported component are all specified in the same fashion as described in the previous example. However, the tr-181-2-1 document updates are specified somewhat differently.

The tr-181-2-1 document imports the NSLookupDiagDiffs component from the tr-157-1-3 document. Since this component is not updated within the tr-181-2-1 document (i.e. read-only), it is imported using the import/component/@name attribute alone (i.e. omits the ref attribute; this means that the NSLookupDiagDiffs component is referred to locally by the same name that it is defined by in the remote document). Finally, the model/component element references the NSLookupDiagDiffs component in order to include the component updates within the revised model.