Home Community User Groups Special Interest Groups NI Tools Network Developer Center Developer Center Blog Post

Developer Center Blog

Community Browser
cancel
Turn on suggestions
Showing results for 
Search instead for 
Did you mean: 

How to Change Connector Panes in New Versions of an API

Roso
NI Employee (retired)
‎03-16-2012 02:19 PM
‎03-16-2012 02:19 PM

When developing a new version of an API, have you ever wanted to change a connector pane, but were worried about backwards compatibility for existing users or customers?  Here is one idea to solve this problem.

When changing the terminal assignment of an icon, you can maintain backwards compatibility by creating a wrapper around the existing function with the new terminal assignment and replacing the old function in your palette with the new VI.  Your old function should then be included under your source code directory (in \vi.lib\).  This ensures existing users' code will still locate the dependency after upgrading, but new users and new code can utilize the new VI and terminal assignment.

To demonstrate, take the fictitious example of an OpenG function where the 'dup VI reference' terminal is in a location other than the recommended 'reference' wire location in the top left & right terminals:

   pane1.png

If a developer were to release an update where they had modified the terminal location to set it to the recommended top-right terminal, the old VI would be broken:

pane2.png

Now, if instead the developer were to create a wrapper around this function with the correct assignment and replace the palette entry with the new wrapper VI, old applications will still work and new applications can make use of the new assignment:

pane3.png

Notice, you can also edit the icon for the old version to indicate the function was deprecated.  We recommend documenting this in your upgrade notes and VI description for the old function so users know why the change was made and realize it will not negatively impact execution if left as is.

That's all there is to it!

One caveat to note: the new VI will need to have a different filename from the old one, but you can keep the same name in the palette.

For help re-packaging the new API using VI Package Manager, click here.

For help customizing palettes with VI Pakcage Manager, click here.

Comments
Active Participant
Active Participant
‎03-16-2012 02:34 PM
‎03-16-2012 02:34 PM

For object-oriented APIs, you can use the Decorator design pattern to achieve the same result.

0 Kudos
jgcode
Active Participant
Active Participant
‎03-17-2012 12:25 AM
‎03-17-2012 12:25 AM

Great post Roso, and I really like your OpenG examples

I am the OpenG Manager and this is pretty close to how we actually handle deprecation in OpenG.

I would like to add my experiences to, as well as discussing the OpenG deprecation process in, this interesting topic - and to encourage other developers to discuss how they manage deprecation in their code libraries.

(Note: OpenG libraries are currently made up of non-.lvlib reusable VIs and does not include LVOOP APIs).

A few of the main reasons we need to deprecate functions include:

  • Connector pane changes - as mentioned the location of existing inputs/outputs changes or the CP pattern itself changes. Pattern changes can be mitigated somewhat at design time e.g. choosing a pattern that has spare inputs/outputs
  • Behavioural changes - the VI was fixed/modified and now the same inputs return different outputs
  • Redundancy - the exact same functionality is now included in LabVIEW or refactoring of the underlying code (due to e.g. changes in LabVIEW) makes the third-party VI a simple one node wrapper

The end focus is always about not breaking end users existing code of course!

Because maintenance of duplicate code is an issue (with respect to changes, testing etc...) wrapping the function is highly advisable as long as there are no behavioural changes.

Contrariwise, in OpenG the deprecated function becomes a wrapper around the new function and the original code is moved to the new VI's BD. Then there is no dependency on the deprecated VI from the new VI's perspective - so the deprecated VI may later be marked for not-supported and hence removed in a future package release (OpenG does not currently do this though) - without causing relinking issues. Additionally from here on in, all changes will be made to only the new VI.

Notifying end users that a VI has become deprecated can be done is several ways (documentation, support forums, VIPM release notes etc...) but as LabVIEW is graphical by nature the most convenient way is definitely the icon. The example presented does obfuscate the original icon slightly. OpenG changes the background to a distinctive red/pink (RGB: 253,153,153), keeping the original images intact. Additionally the FP comment, BD comment and VI description are changed to notify the user about reasons for the deprecation and also what VI to use instead. The deprecated VI is removed from the palette and where applicable, the new VI is added in it's place.

Renaming is accomplished using an incremental numerical suffix - which keeps things simple and logical.

Here is a real example from OpenG that highlights this process:

Slice String is part of the OpenG String Library. A bug was found in Slice String whereby a optional input was wired on the right hand side making it ap...

As changing the location of the input would break existing code, the function was deprecated and information added to the FP, BD and VI description.

Slice String.pngSlice1.png

Slice String FP.png

Because there were no behavioural changes, the deprecated function was wrapped around the new function. This would not affect any users calling this code. If in the future there was a need for behavioural changes to be committed to this new VI, then it would be deprecated first - still protecting the original deprecated VI! 

Slice String BD.png

The original code was moved to the new VI's BD so any changes would occur here.

Slice String 1 BD.png

The new VI would then replace the depreacted VI in the palette, but would appear the same (both in icon and palette name). And then this code would be released in a new VIPM package.

----------

Deprecating Array functions becomes alot of work when that function is e.g. a polymorphic VI that supports n datatypes (where n is large). Having the ability to create generic VIs in the future sure would be great.

Another topic that relates to this one is how to extend a single VI into a Polymorphic API whilst maintaining backwards compatibility (not breaking existing code) in order to support additional datatypes etc... OpenG has a process for that as well that I would be happy to discuss.

Regards

-Jonathon Green

Certified LabVIEW Architect * LabVIEW Champion