Interface AnjayFirmwareUpdateHandlers
-
public interface AnjayFirmwareUpdateHandlersHandler callbacks that shall implement the platform-specific part of firmware update process.The Firmware Update object logic may be in one of the following states:
- Idle. This is the state in which the object is just after creation (unless
initialized with either
DOWNLOADEDorDOWNLOADING. The following handlers may be called in this state:streamOpen()- shall open the download stream; moves the object into the Downloading stategetSecurityConfig(java.lang.String)- shall fill in security info that shall be used for a given URLreset()- shall cleanup the object state if neccessary
- Downloading. The object might be initialized directly into this state by
using
DOWNLOADING. In this state, the download stream is open and data may be transferred. The following handlers may be called in this state:streamWrite()- shall write a chunk of data into the download stream; it normally does not change state - however, if it fails, it will be immediately followed by a call toreset()streamFinish()- shall close the download stream and perform integrity check on the downloaded image; if successful, this moves the object into the Downloaded state. If failed - into the Idle state; note thatreset()will NOT be called in that casereset()- shall remove all downloaded data; moves the object into the Idle state
- Downloaded. The object might be initialized directly into this state by
using
DOWNLOADED. In this state, the firmware package has been downloaded and checked and is ready to be flashed. The following handlers may be called in this state:reset()- shall reset all downloaded data; moves the object into the Idle stategetName()- shall return the package name, if availablegetVersion()- shall return the package version, if availableperformUpgrade()- shall perform the actual upgrade; if it fails, it does not cause a state change and may be called again; upon success, it may be treated as a transition to a "terminal" state, after which the device is expected to reboot
- Idle. This is the state in which the object is just after creation (unless
initialized with either
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default Anjay.CoapUdpTxParamsgetCoapTxParams(java.util.Optional<java.lang.String> downloadUri)Returns CoAP transmission parameters used to override default ones.java.lang.StringgetName()Returns the name of downloaded firmware package.default AnjaySecurityConfiggetSecurityConfig(java.lang.String uri)Queries security information that shall be used for an encrypted connection with a PULL-mode download server.java.lang.StringgetVersion()Returns the version of downloaded firmware package.voidperformUpgrade()Performs the actual upgrade with previously downloaded package.voidreset()Resets the firmware update state and performs any applicable cleanup of temporary storage if necessary.voidstreamFinish()Closes the download stream and prepares the firmware package to be applied.voidstreamOpen(java.util.Optional<java.lang.String> packageUri, java.util.Optional<byte[]> etag)Opens the stream that will be used to write the firmware package to.voidstreamWrite(byte[] data)Writes data to the download stream.
-
-
-
Method Detail
-
streamOpen
void streamOpen(java.util.Optional<java.lang.String> packageUri, java.util.Optional<byte[]> etag) throws java.lang.ExceptionOpens the stream that will be used to write the firmware package to.The intended way of implementing this handler is to open a temporary file using or allocate some memory buffer that may then be used to store the downloaded data in. The library will not attempt to call
streamWritewithout having previously calledstreamOpen().Note that this handler will NOT be called after initializing the object with the
DOWNLOADINGstate, so any necessary resources shall be already open before calling @refinstall().- Parameters:
packageUri- URI of the package from which a Pull-mode download is performed, or empty if it is a Push-mode download. This argument may either be ignored, or persisted in non-volatile storage if the client supports download resumption after an unexpected reboot (seeAnjayFirmwareUpdate.InitialStateand its fields).etag- ETag of the data being downloaded in Pull mode, or empty if it is a Push-mode download or ETags are not supported by the remote server. This argument may either be ignored, or persisted in non-volatile storage if the client supports download resumption after an unexpected reboot (seeAnjayFirmwareUpdate.InitialStateand its fields).- Throws:
java.lang.Exception- In case of failure.
-
streamWrite
void streamWrite(byte[] data) throws AnjayFirmwareUpdateExceptionWrites data to the download stream.May be called multipled times after
streamOpen(), once for each consecutive chunk of downloaded data.- Parameters:
data- Chunk of the firmware package being downloaded. Guaranteed to be non-null.- Throws:
AnjayFirmwareUpdateException- In case of failure. The corresponding value will be set in the Update Result Resource.
-
streamFinish
void streamFinish() throws AnjayFirmwareUpdateExceptionCloses the download stream and prepares the firmware package to be applied.Will be called after a series of
streamWrite()calls after the whole package is downloaded.The intended way of implementing this handler is to e.g. close the file and perform integrity check on it. It might also be uncompressed or decrypted as necessary, so that it is ready to be applied. The exact split of responsibility between
streamFinish()andperformUpgrade()is not clearly defined and up to the implementor.Note that regardless of the exception thrown, the stream is considered to be closed. That is, upon successful return, the Firmware Update object is considered to be in the Downloaded state, and upon throwing an exception - in the Idle state.
- Throws:
AnjayFirmwareUpdateException- In case of failure. The corresponding value will be set in the Update Result Resource.
-
reset
void reset()
Resets the firmware update state and performs any applicable cleanup of temporary storage if necessary.Will be called at request of the server, or after a failed download. Note that it may be called without previously calling
streamFinish(), so it shall also close the currently open download stream, if any.
-
getName
java.lang.String getName()
Returns the name of downloaded firmware package.The name will be exposed in the data model as the PkgName Resource. If this callback returns
nullor is not implemented at all, that Resource will not be present in the data model.It only makes sense for this handler to return non-
nullvalues if there is a valid package already downloaded. The library will not call this handler in any state other than Downloaded.- Returns:
- The callback shall return the package name, or
nullif it is not currently available.
-
getVersion
java.lang.String getVersion()
Returns the version of downloaded firmware package.The version will be exposed in the data model as the PkgVersion Resource. If this callback returns
nullor is not implemented at all, that Resource will not be present in the data model.It only makes sense for this handler to return non-
nullvalues if there is a valid package already downloaded. The library will not call this handler in any state other than Downloaded.- Returns:
- The callback shall return the package version, or
nullif it is not currently available.
-
performUpgrade
void performUpgrade() throws AnjayFirmwareUpdateExceptionPerforms the actual upgrade with previously downloaded package.Will be called at request of the server, after a package has been downloaded.
Most users will want to implement firmware update in a way that involves a reboot. In such case, it is expected that this callback will do either one of the following:
- return, causing the outermost event loop to terminate, shutdown the library and then perform the firmware upgrade and then the device to reboot
- perform the firmware upgrade internally and never return, causing a reboot in the process.
After rebooting, the result of the upgrade process may be passed to the library during initialization via the
InitialResultargument toinstall().Alternatively, if the update can be performed without reinitializing Anjay, you can use
AnjayFirmwareUpdate.setResult(Result)(either from within the handler or some time after returning from it) to pass the update result.- Throws:
AnjayFirmwareUpdateException- The callback shall throw an exception if it can be determined without a reboot that the firmware upgrade cannot be successfully performed. The corresponding value will be set in the Update Result Resource.
-
getSecurityConfig
default AnjaySecurityConfig getSecurityConfig(java.lang.String uri)
Queries security information that shall be used for an encrypted connection with a PULL-mode download server.May be called before
streamOpen(java.util.Optional<java.lang.String>, java.util.Optional<byte[]>)if the download is to be performed in PULL mode and the connection needs to use TLS or DTLS encryption.If this handler is not implemented at all or
nullis returned, Anjay will attempt to obtain security information from Data Model (in a way equivalent to howAnjay.securityConfigFromDm(java.lang.String)works). You may also use this function yourself, for example as a fallback mechanism.- Parameters:
uri- URI on which the download will be started.- Returns:
- instance of
AnjaySecurityConfigornull.
-
getCoapTxParams
default Anjay.CoapUdpTxParams getCoapTxParams(java.util.Optional<java.lang.String> downloadUri)
Returns CoAP transmission parameters used to override default ones.If this handler is not implemented at all or
nullis returned, tx params fromAnjayobject are used.- Parameters:
downloadUri- Target firmware URI.- Returns:
- Object with CoAP transmission parameters.
-
-