|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.ibm.datapower.wamt.clientAPI.Firmware
public class Firmware
A container for firmware images.
A firmware image for a device is uniquely identified by 5 pieces of information:
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.
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 |
---|
public static final java.lang.String COPYRIGHT_2009_2013
Method Detail |
---|
public DeviceType getDeviceType() throws DeletedException
setDeviceType
method.
public ModelType getModelType() throws DeletedException
setModelType
method.
public ModelType[] getCompatibleModelTypes() throws DeletedException
setModelType
method.
public StringCollection getStrictFeatures() throws DeletedException
setStrictFeatures
method.
public StringCollection getNonstrictFeatures() throws DeletedException
setNonstrictFeatures
method.
public java.lang.String getPrimaryKey() throws DeletedException
public int getHighestVersionNumber() throws DeletedException
getVersions()
, and FirmwareVersion.getLevel()
.
public static Firmware getByPrimaryKey(java.lang.String targetKey)
targetKey
- the primary key to search for
null
if no Firmware with the specified primary key
was found.getPrimaryKey()
public void remove(Version version) throws InUseException, InvalidParameterException, DeletedException, DatastoreException
public Version[] getVersions() throws DeletedException
Versionable
This object should implement the Versionable
interface,
and versions of this object should implement the Version
interface.
getVersions
in interface Versionable
Versionable.getVersion(int)
public Version getVersion(int targetVersionNumber) throws DeletedException
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
.
Versionable
getVersion
in interface Versionable
targetVersionNumber
- the specified version to get of this object.
Versionable.getVersions()
public FirmwareVersion getLevel(java.lang.String targetLevel) throws DeletedException
targetLevel
- the FirmwareVersion level to search for, i.e.,
"3.6.0.1"
null
.public java.lang.String toString()
toString
in class java.lang.Object
public java.lang.String getDisplayName()
public boolean isCompatibleWith(Device 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:
XS40=XS40
9003=9003
or other=9002
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"])
device["JAXP", "Tibco-EMS"].isSupersetOf(firmware["Tibco-EMS"])
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.
device
- the device to check for compatibility with this Firmware
getIncompatibilityReason(Device)
,
Utilities.getFirmwareDeviceType(Blob)
,
Utilities.getFirmwareModelType(Blob)
,
Utilities.getNonStrictFirmwareFeatures(Blob)
,
Utilities.getStrictFirmwareFeatures(Blob)
,
Commands.getDeviceMetaInfo(com.ibm.datapower.wamt.amp.DeviceContext)
public java.lang.String getIncompatibilityReason(Device device)
device
- the Device to check for compatibility to this Firmware
isCompatibleWith(Device)
,
Device.createDevice(String, String, String, String, int)
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |