com.ibm.datapower.wamt.clientAPI
Class Firmware

java.lang.Object
  extended by com.ibm.datapower.wamt.clientAPI.Firmware
All Implemented Interfaces:
Versionable

public class Firmware
extends java.lang.Object
implements Versionable

A container for firmware images.
A firmware image for a device is uniquely identified by 5 pieces of information:

This object (Firmware) represents the first four items in the list. The last element is represented by FirmwareVersion. The Firmware object serves as a container for one or more levels (e.g., one or more FirmwareVersion objects). Note that the firmware levels in more than one Firmware object may work for a particular device (e.g be deployable because of matching DeviceType, ModelType, and StrictFeatures), but one may be preferred over the other because of the non-strict features supported by the firmware.

Firmware objects are always created by the Manager. Firmware objects are automatically created, if necessary, when Manager.addFirmware(Blob, String) is called. If a matching Firmware already exists in the manager, then a FirmwareVersion is added to the Firmware. An array of all Firmware objects can be retrieved from the manager by calling Manager.getFirmwares().

It is not possible to export a firmware image from a device, so the Firmware class has a slightly different behavior than Domain.

The versionNumber information from the Version interface doesn't mean much, it is an opaque integer (i.e., "2") that is different than the Level (i.e., "3.6.0.1") in a FirmwareVersion. Almost always when dealing with a FirmwareVersion, you will want to look at getLevel(String) instead of getVersion.

The organization of firmware is more complicated that you might assume. Take a deep breath and read on.

DataPower firmware is packaged to be optimized for download size, installed memory space, and some other constraints such as licenses (described below). So a single firmware image has the binaries only for one DeviceType, one ModelType, a (mostly) global set of non-strict features, and a specific set of strict features. It is not the case that there is a unified single firmware image that can be applied across a variety of devices.

In DataPower firmware, the DeviceType is important because each DeviceType has a different set of capabilities, even if they have similar hardware. So the firmware will be different for each DeviceType. A firmware image is compatible only with the intended DeviceType.

Also, the ModelType infers the hardware revision. There are different firmware binaries for different ModelTypes. A firmware image is compatible only with the intended ModelType.

DataPower devices may have optional features enabled or disabled at the factory. The enablement of these features is controlled via licenses embedded in the device. Generally, but not always, these features are software-based and do not require any special hardware. Thus, generally, these features are implemented by including a license on the device and embedding extra code (libraries) in the firmware.

There are two kinds of features: strict and non-strict. Non-strict features may be distributed and installed to any device, even to a device that is not licensed for that feature. In the case where a device is not licensed for a non-strict feature but firmware for that non-strict feature is installed on the device, the feature is simply disabled on that device. In comparison, strict features may be distributed and installed only to devices that are licensed for that feature. The reason for a feature being designated as strict is usually because it is licensed from a third-party, and the license agreement with the third-party limits distribution only to devices which are licensed. In those cases it is not acceptable based on the license to distribute code for a strict feature to a device that is not licensed for it, even if the strict feature is disabled - the third-parties do not want the code to be resident on the device even if it doesn't run. The manager limits the notion of features even further because it will not install a firmware that does not contain all of the features (strict and non-strict) that a device is licensed to use.

For a description of how to determine if firmware is compatible with a specific device, see isCompatibleWith(Device). The lowest level of firmware supported a device may be checked with FirmwareVersion.meetsMinimumLevel(String). Arbitrary version checking can be done with FirmwareVersion.meetsMinimumLevel(String, String), and Device.meetsMinimumFirmwareLevel(String) can be used to see if the actual firmware deployed to a device meets a specific firmware level requirement.

There are two versions of firmware packaging. The older is scrypt or first generation, the newer is scrypt2 or next generation. Only the next generation is supported here, as we need certain header information which is present only in the next generation.

See Also:
FirmwareVersion

Field Summary
static java.lang.String COPYRIGHT_2009_2013
           
 
Fields inherited from interface com.ibm.datapower.wamt.clientAPI.Versionable
COPYRIGHT_2009_2010, SCM_REVISION
 
Method Summary
static Firmware getByPrimaryKey(java.lang.String targetKey)
          Retrieve a reference to the Firmware that has the specified primary key.
 ModelType[] getCompatibleModelTypes()
          Get all ModelTypes that are compatible with the ModelType of this Firmware.
 DeviceType getDeviceType()
          Get the DeviceType of this Firmware.
 java.lang.String getDisplayName()
          Get a human-readable name that represents this object.
 int getHighestVersionNumber()
          Get the highest version number of all the FirmwareVersions in this Firmware.
 java.lang.String getIncompatibilityReason(Device device)
          Gets the text description of the reason why this Firmware is incompatible with the device of the specified properties.
 FirmwareVersion getLevel(java.lang.String targetLevel)
          Get the FirmwareVersion object that corresponds to the requested level.
 ModelType getModelType()
          Get the ModelType of this Firmware.
 StringCollection getNonstrictFeatures()
          Get the non-strict features that are in this Firmware.
 java.lang.String getPrimaryKey()
           
 StringCollection getStrictFeatures()
          Get the strict features that are in this Firmware.
 Version getVersion(int targetVersionNumber)
          Deprecated. Instead of this method you probably want to use getLevel(String). A level is a String value (i.e., "3.6.1.0") which is probably what you are searching for. The version number in a FirmwareVersion object will be an opaque int and not anything meaningful to the user. This method will return a valid value when invoked with a valid parameter (i.e., 2), but you probably want to use getLevel.
 Version[] getVersions()
          Get all the versions that exist of this Versionable object.
 boolean isCompatibleWith(Device device)
          Test if the Firmware and the Device are compatible, which means that the Firmware could run on the Device.
 void remove(Version version)
           
 java.lang.String toString()
          Get a String representation of this object for the purpose of debugging or tracing.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

COPYRIGHT_2009_2013

public static final java.lang.String COPYRIGHT_2009_2013
See Also:
Constant Field Values
Method Detail

getDeviceType

public DeviceType getDeviceType()
                         throws DeletedException
Get the DeviceType of this Firmware. Firmware is specific to device types. The deviceType is immutable, so there is no setDeviceType method.

Returns:
the device type that this firmware must run on

getModelType

public ModelType getModelType()
                       throws DeletedException
Get the ModelType of this Firmware. Firmware is specific to the model type. The model type is immutable, so there is no setModelType method.

Returns:
the ModelType that this firmware must run on

getCompatibleModelTypes

public ModelType[] getCompatibleModelTypes()
                                    throws DeletedException
Get all ModelTypes that are compatible with the ModelType of this Firmware. Firmware is specific to the model type. The model type is immutable, so there is no setModelType method.

Returns:
array of ModelType that are compatible with this firmware. Returned array will always contain the modelType of this firmware, since it will be compatible with itself.

getStrictFeatures

public StringCollection getStrictFeatures()
                                   throws DeletedException
Get the strict features that are in this Firmware. The device you are trying to apply this Firmware to must have exactly the same list of strict licensed features. The strict features are immutable, so there is no setStrictFeatures method.

Returns:
the list of strict features that this firmware has and that the device must be licensed for

getNonstrictFeatures

public StringCollection getNonstrictFeatures()
                                      throws DeletedException
Get the non-strict features that are in this Firmware. This Firmware must have all the non-strict features that the device is licensed for. Otherwise the device would not have the code for all the features it is licensed for. The non-strict features are immutable, so there is no setNonstrictFeatures method.

Returns:
the list of non-strict features that this firmware has. This may be a superset of the licensed non-strict features for the device

getPrimaryKey

public java.lang.String getPrimaryKey()
                               throws DeletedException

getHighestVersionNumber

public int getHighestVersionNumber()
                            throws DeletedException
Get the highest version number of all the FirmwareVersions in this Firmware. You may be more interested in the firmware level (i.e., "3.6.0.1") than the version number (i.e., 2), so instead consider using getVersions(), and FirmwareVersion.getLevel().

Returns:
the highest version number of all the FirmwareVersions, i.e., 2

getByPrimaryKey

public static Firmware getByPrimaryKey(java.lang.String targetKey)
Retrieve a reference to the Firmware that has the specified primary key.

Parameters:
targetKey - the primary key to search for
Returns:
the Firmware that has the specified primary key. May return null if no Firmware with the specified primary key was found.
See Also:
getPrimaryKey()

remove

public void remove(Version version)
            throws InUseException,
                   InvalidParameterException,
                   DeletedException,
                   DatastoreException

getVersions

public Version[] getVersions()
                      throws DeletedException
Description copied from interface: Versionable
Get all the versions that exist of this Versionable object.

This object should implement the Versionable interface, and versions of this object should implement the Version interface.

Specified by:
getVersions in interface Versionable
Returns:
an array of objects which describe all the versions of this object.
See Also:
Versionable.getVersion(int)

getVersion

public Version getVersion(int targetVersionNumber)
                   throws DeletedException
Deprecated. Instead of this method you probably want to use getLevel(String). A level is a String value (i.e., "3.6.1.0") which is probably what you are searching for. The version number in a FirmwareVersion object will be an opaque int and not anything meaningful to the user. This method will return a valid value when invoked with a valid parameter (i.e., 2), but you probably want to use getLevel.

Description copied from interface: Versionable
Get the specified Version of this Versionable object. Versions are specified by a version number, which is a monotomically increasing integer that should be unique across this Versionable object.

Specified by:
getVersion in interface Versionable
Parameters:
targetVersionNumber - the specified version to get of this object.
Returns:
the specified version of this object. May return null if no version of the specified number exists.
See Also:
Versionable.getVersions()

getLevel

public FirmwareVersion getLevel(java.lang.String targetLevel)
                         throws DeletedException
Get the FirmwareVersion object that corresponds to the requested level. The FirmwareVersion must exist as a Version of this Firmware object. For example it is possible to have a "3.6.0.1" level for XS40 devices but not for XI50 devices - using this method to look for the "3.6.0.1" level within the XI50 Firmware object will return null.

Parameters:
targetLevel - the FirmwareVersion level to search for, i.e., "3.6.0.1"
Returns:
the FirmwareVersion object that has the requested level. If no FirmwareVersion object exists with the requested level, then it returns null.

toString

public java.lang.String toString()
Get a String representation of this object for the purpose of debugging or tracing.

Overrides:
toString in class java.lang.Object
Returns:
a String representation of this object for the purpose of debugging or tracing.

getDisplayName

public java.lang.String getDisplayName()
Get a human-readable name that represents this object. This name may be used in user interfaces.

Returns:
a human-readable name that represents this object. For example, "for device type XS40 and model type 9003 with the strict features Tibco-EMS, TAM, and with the non-strict features JAXP-API, HSM"

isCompatibleWith

public boolean isCompatibleWith(Device device)
Test if the Firmware and the Device are compatible, which means that the Firmware could run on the Device.

Please review the class javadoc at the top of this file for an explanation of the 5-tuple that uniquely identifies firmware, including strict and non-strict features.

In the examples below, "JAXP-API" and "HSM" are non-strict features, and "Tibco-EMS" is a strict feature. (There are many more features in real life than these three.) We will assume that the firmware has the features ["JAXP-API", "HSM", "Tibco-EMS"] and the device is licensed for the features ["JAXP-API", "Tibco-EMS"].

All of the four following conditions must exist for a firmware to be compatible with a device:

  1. the DeviceType of the firmware and the device must match exactly. For example, XS40=XS40
  2. the ModelType of the firmware and the device must match exactly. For example, 9003=9003 or other=9002
  3. all the features in the firmware must be a superset of the licensed features of the device. In other words, all the features that the device is licensed for must be present in the firmware. (Based on the implementation of isSupersetOf, that method evaluates to true if there are zero extra elements in the sets, meaning that each set has exactly the same elements as the other set.) The reason for doing this check is that we never want the code for a licensed feature to be missing from the device, which would effectively disable the feature. While this makes sense for non-strict features, it may sound counter-intuitive for strict features because no extra strict features from the firmware are allowed on the device. However, because the device isn't able to tell us via AMP which of its features are strict versus non-strict (we get only a unified list of the device's feature when we query the device), and when this condition is combined with the condition below, it all works. For example, firmware["JAXP", "HSM", "Tibco-EMS"].isSupersetOf(device["JAXP", "Tibco-EMS"])
  4. the features of the device must be a superset of the firmware's strict features. In other words, the device must be licensed for all the strict features present in the firmware. An attempt to install a firmware with strict features on a device that is not licensed for that strict feature will result in a device's failure to install that firmware. Since we want to prevent users from going down a path that we know ahead of time will result in failure, we perform that check here to catch it early. If the firmware has any strict features not present in the device then this test will fail. For example, device["JAXP", "Tibco-EMS"].isSupersetOf(firmware["Tibco-EMS"])

The firmware level (i.e., "3.6.1.2") is not included in the compatibility test. If the other 4 elements of the 5-tuple indicate that the firmware is compatible with the device, then any version may be applied to the device. This is what is meant as upgrading or downgrading firmware.

The get* methods from the Utilities class listed as "See Also" below that take a Blob parameter are where the metadata is retrieved from the firmware images. The Device constructor is where the metadata is retrieved from the device.

Parameters:
device - the device to check for compatibility with this Firmware
Returns:
true if the compatible, false otherwise
See Also:
getIncompatibilityReason(Device), Utilities.getFirmwareDeviceType(Blob), Utilities.getFirmwareModelType(Blob), Utilities.getNonStrictFirmwareFeatures(Blob), Utilities.getStrictFirmwareFeatures(Blob), Commands.getDeviceMetaInfo(com.ibm.datapower.wamt.amp.DeviceContext)

getIncompatibilityReason

public java.lang.String getIncompatibilityReason(Device device)
Gets the text description of the reason why this Firmware is incompatible with the device of the specified properties. This text may be used in user interface messages. If the the firmware and device are compatible, this will return a null String (a null incompatibility means they are compatible).

Parameters:
device - the Device to check for compatibility to this Firmware
Returns:
an explanation why the Firmware is incompatible. Will return null if the Firmware is compatible with the Device (a null incompatibility means they are compatible).
See Also:
isCompatibleWith(Device), Device.createDevice(String, String, String, String, int)


© Copyright IBM Corp. 2006, 2010 All Rights Reserved.