All This email details an attempt by me to model the NETCONF specification in UML in preparation for implementing the specification. My basic conclusion was that the specification can not be implemented as it currently stands. I welcome challenges to that conclusion. Viewing the project and using Together -------------------------------------- This is the first step in modelling NETCONF, which is to represent the entities and their relationships in UML. For those who want to play with the Together project itself, I have attached the whole thing zipped. If you want to edit the project, you will need to get Together 6.1 from Borland.com (just fill in the evaluation form and download it) an apply for an evaluation licence if you need it. You don't need Together to view the diagrams, which are gifs, or the code, all of which are in the attached zip file. Once you have done that, open the attached file somewhere convenient, windows or Linux/Unix. Open the NETCONF.tpr file, and you will be away! If you just want to look at the diagrams, then they are in the diagrams directory of the attached file. There are two diagrams, netconf.gif and rpc.gif. There are also many notes in the source files also, which are under src, which you can look at with the aid of a normal editor. Discussion of the model - Operations and arguments -------------------------------------------------- Whilst this is a UML *model*, and is thus distinct from any specific implementation, implementation concerns always play a role in modelling, much as normalization does in data base modelling. I have thus approached this modelling exercise as though I were going to implement the specification, as indeed I am, from a top down perspective, rather than the bottom up approach that the specification takes. One of the first challenges that I encountered with reverse engineering a model from the specification was separating the RPC implementation from the operations. Having the rpc-reply element as part of the signature of the operations, the fact that some arguments are parameters, whilst others are attributes, and the use of '<>'s everywhere couples the operations to the underlying XML implementation. This coupling is probably not the intention of the specification writers, but it is there nevertheless. Another challenge was the inconsistent declaration of "format" argument. It is implied in the text descriptions, so I have included a Format object as an operation parameter which is an enumeration of two types: XML and Text. I suspect that there may be more types, and using an enumeration is intrinsically extensible. The next challenge was to decide what the Configuration type should look like. I have used a nested structure. This is a common design idiom where a top level container contains a collection of something - ConfigurationElement - that is a name/value pair, or a collection of more of itself. Again, this is intrinsically extensible. I then needed to think about what the naming and types of the parameters should be. I wasn't sure what the notation used in the specification was meant to convey. An example being "source: @config-name". I took this to mean that there was a parameter called source, which is the name of a configuration, though the explanation refers to this being the name of a configuration datastore. In general I took the first part of the parameter name for the arguments for the operations where that made sense. I also used String types by default, except where the type was more specifically defined, either because my modelling interpretation introduced it, or because it was later specified by the Capabilities. With the "config: @element-subtree" parameter, I made the decision that this was actually the scope of the operation, that being the implication of the explanation. In any case, I was able to use the same Configuration type as the argument and the value of the configuration in the reply, which was a useful modelling outcome, and may be what the specification writers intended. The RPCreply type is a common pattern for RPCs where the encoding and/or the implementation don't support exceptions. In this case we have a container for the configuration, state and rpc-error elements. This can be used over any RPC encoding scheme, which I believe was the intention of the specification writers. The State type posed a problem as it clearly exists in the specification, but there is no indication of what it consists of. For now I have included the type as a place holder, but I am unable to give it any structure. The RPCError type probably has more members than it needs. A minimum for such a type would normally be the error code, non internationalised error text, and a namespace to define the resource bundle that the internationalised text would come from. The specification writers might want to consider whether all of the other elements are really needed. The edit-config operation specifies attributes as well as parameters. This is XML specific. I have modelled the "operation" attribute as a parameter to the operation and created an enumerated type, EditOperation. This also illustrates that having a parameter to an operation called "operation" is not a good thing. It might have been better to have three separate edit operations instead, which is another modelling option that I considered, but have left out for now. The copy-config operation has a source parameter which could be a name of a configuration or a configuration itself. Since these are two different types, I have had to create two arguments in the operation for both cases. This is also the only operation where the format parameter is explicitly specified, but it is also suggested that the format be omitted for this operation. I wasn't sure what to make of that, so I included format as a parameter anyway. The get-all operation specifies a state parameter which could be an element-subtree (which I have modelled as a Configuration type specifying the scope of the operation) or text. This led me to conclude that the specification writers intended for there to be a format parameter, so I have created one for this operation. The kill-session operation specified the type of session-id to be an integer. This is the first type definition in the specification. I can see that the session-id is elsewhere specified as an int, but it might better be a float, or a BIGINT. There is no guarantee on how big an int can be, but at least we can decide on an IEEE defined float as a number with a well specified range. Further, a positive integer means that we can't use -1 as a session-id which can sometimes be useful. Discussion of the model - Capabilities etc. ------------------------------------------- The next step in the modelling exercise is to decide how to model Capabilities and the different operations associated with devices that have them. The first point of difficulty is that the capabilities of a device are determined during the transport set up when the session is first established as part of the "hello" handshake. This is not a good thing. I have added an operation to the Device type (more on that later) which supports the explicit discovery of capabilities after the transport has been established. The Device type could have been called Server as the specification uses both interchangeably. This is not a good idea. Typically the "server" would, for most people, be the management software managing the device. Since this is a peer-to-peer model, moreover, neither is really a server in the client-server sense. The specification writers seem to have taken the stance that the entity implementing the operations is the server. I have chosen "Device" as that is much clearer. I'd suggest that the specification writers do the same. The Capability type is modelled with a namespace and a type which is modelled as an enumeration. A Device has a collection of Capability(s). Each capability has associated with it a set of operations which are additive in that a device can have the base operations, and the extra operations associated with the additional capabilities. A problem arises in that some base operations are overloaded, i.e. redefined, in a device that has a capability. Normally this would be modelled by inheritance which would allow an operation in an inherited type to redefine what the base operation does. In this case, as the capabilities are additive, but not mutually exclusive, it is not clear how this would work. What happens, for example, if a device has both the URL capability and the Candidate capability? Both these capabilities define different versions of edit-config. Which would apply? For the time being I have chosen to model the operations as a collection in the Device conceptually keyed by the capability that the operations are associated with. This really makes the notion of a capability more like that of a role. If that were the case, then one could decide what role the device was fulfilling, and then choose the set of operations that matched that role/capability. As things stand I am not sure if the model is correct or not, or whether the specification writers have simply left this aspect unspecified. The specification defines an Agent capability, but all this seems to indicate is that a peer is willing to be managed, which makes it a Device. I think that the Manager and Agent capabilities are not capabilities at all, but roles. It is also not clear what difference they make in an implementation, except perhaps at the transport security level. Where the capabilities modify existing operations, this is typically in a way that defines what the values of the arguments should be. In these cases this is not a modification of the operation, it is an implementation detail of how the operation should work. The edit-config and copy-config operations for the Writeable-Running capability are examples of this. A slightly different case is the modification to the copy-config operation for the Distinct Startup capability, which appears to specify a completely different behaviour from the base operations. I have tried to capture the new and modified operations by redefining the operations on a specific derived Operations type for the associated capability. The diagram only reveals part of the story, so the notes in the code will help to see what I have done here. The discard-changes operation for the Candidate Configuration capability doesn't appear to have a return value, but I have added one as it is clearly required. The get-config and edit-config modified operations for the Candidate capability are specified to have a default target of the candidate configuration. This should probably be the only value allowed. For it to be described as "default" implies that there is a choice of some other configuration, which wouldn't make sense for this capability. Also, "target" probably means source for get-config, and target for edit-config only. As per the modelling question above, it is not clear whether a device can have the Validate and Candidate capabilities at the same time. On a point of consistency, the section for the Validate capability doesn't mention any modifications to existing operations at all. Summary ------- This review has highlighted some shortcomings in the specification from an implementation perspective, and also from a system model perspective. Ideally these would be addressed so that a definitive model could be produced. That's all for now. I'd appreciate some feedback on this discussion. Many thanks Nathan -- Nathan Sowatskey - Technical Leader, NMTG CTO Engineering - Desk +44-208-824-4259/+1-408-527-2595 - Mobile +44-7740-449794 - AIM id NathanCisco - nsowatsk@cisco.com
Attachment:
NETCONF_together_project.tar.gz
Description: application/compressed-tar