Interface AnjayObject


  • public interface AnjayObject
    Interface specifying handlers for operations on Object's Instances and Resources.

    LwM2M Object may also implement AnjayObjectAttrHandlers interface.

    • Method Detail

      • oid

        int oid()
        A handler that returns Object ID.
        Returns:
        Object ID.
      • version

        default java.lang.String version()
        A handler that returns version of the object.
        Returns:
        Version of the object as string. If not implemented, "1.0" is returned by default.
      • instances

        java.util.SortedSet<java.lang.Integer> instances()
        A handler that returns all Object Instances for the Object.
        Returns:
        SortedSet with Instance IDs.
      • instanceReset

        default void instanceReset​(int iid)
                            throws java.lang.Exception
        A handler that shall reset Object Instance to its default (after creational) state.

        Note: if this handler is not implemented, then non-partial write on the Object Instance will not succeed.

        Parameters:
        iid - Instance ID to reset.
        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • instanceCreate

        default void instanceCreate​(int iid)
                             throws java.lang.Exception
        A handler that creates an Object Instance.

        Note: if this handler is not implemented, LwM2M Server won't be able to create a new object instance.

        Parameters:
        iid - Instance ID to create, chosen either by the server or the library. An ID that has been previously checked to not be PRESENT is guaranteed to be passed.
        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • instanceRemove

        default void instanceRemove​(int iid)
                             throws java.lang.Exception
        A handler that removes an Object Instance with given Instance ID.

        Note: if this handler is not implemented, LwM2M Server won't be able to remove an object instance.

        Parameters:
        iid - Checked Object Instance ID.
        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • resources

        default java.util.SortedSet<AnjayObject.ResourceDef> resources​(int iid)
        A handler that returns SUPPORTED Resources for an Object Instance, called only if the Object Instance is PRESENT (has recently been returned via instances()).
        Parameters:
        iid - Object Instance ID.
        Returns:
        SortedSet with Resource definitions.
      • resourceRead

        default void resourceRead​(int iid,
                                  int rid,
                                  AnjayOutputContext context)
                           throws java.lang.Exception
        A handler that reads the Resource value, called only if the Resource is PRESENT and is one of the AnjayObject.ResourceKind.R or AnjayObject.ResourceKind.RW kinds (as returned by resources(int)).

        If not implemented, Method Not Allowed CoAP code is sent in response.

        Parameters:
        iid - Object Instance ID.
        rid - Resource ID.
        context - Output context to write the resource value to. One of the ret* methods MUST be called in this handler before returning successfully. Failure to do so will result in 5.00 Internal Server Error being sent to the server.
        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • resourceRead

        default void resourceRead​(int iid,
                                  int rid,
                                  int riid,
                                  AnjayOutputContext context)
                           throws java.lang.Exception
        A handler that reads the Resource Instance value, called only if the Resource is PRESENT and is one of the AnjayObject.ResourceKind.RM or AnjayObject.ResourceKind.RWM kinds (as returned by resources(int)) and riid was returned by resourceInstances(int,int).

        If not implemented, Method Not Allowed CoAP code is sent in response.

        Parameters:
        iid - Object Instance ID.
        rid - Resource ID.
        riid - Resource Instance ID.
        context - Output context to write the resource value to. One of the ret* methods MUST be called in this handler before returning successfully. Failure to do so will result in 5.00 Internal Server Error being sent to the server.
        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • resourceWrite

        default void resourceWrite​(int iid,
                                   int rid,
                                   AnjayInputContext context)
                            throws java.lang.Exception
        A handler that writes the Resource value, called only if the Resource is SUPPORTED and not of the AnjayObject.ResourceKind.E kind (as returned by resources(int)). Note that it may be called on nominally read-only Resources if the write is performed by the Bootstrap Server.

        If not implemented, Method Not Allowed CoAP code is sent in response.

        Parameters:
        iid - Object Instance ID.
        rid - Resource ID.
        context - Input context to read the resource value from using the get* methods.
        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • resourceWrite

        default void resourceWrite​(int iid,
                                   int rid,
                                   int riid,
                                   AnjayInputContext context)
                            throws java.lang.Exception
        A handler that writes the Resource Instance value, called only if the Resource is SUPPORTED and is one of the AnjayObject.ResourceKind.RM or AnjayObject.ResourceKind.RWM kind (as returned by resources(int)) and riid was returned by resourceInstances(int,int). Note that it may be called on nominally read-only Resources if the write is performed by the Bootstrap Server.

        If not implemented, Method Not Allowed CoAP code is sent in response.

        Parameters:
        iid - Object Instance ID.
        rid - Resource ID.
        riid - Resource Instance ID.
        context - Input context to read the resource value from using the get* methods.
        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • resourceExecute

        default void resourceExecute​(int iid,
                                     int rid,
                                     java.util.Map<java.lang.Integer,​java.util.Optional<java.lang.String>> args)
                              throws java.lang.Exception
        A handler that performs the Execute action on given Resource, called only if the Resource is PRESENT and of the AnjayObject.ResourceKind.E kind (as returned by resources(int)).

        If not implemented, Method Not Allowed CoAP code is sent in response.

        Parameters:
        iid - Object Instance ID.
        rid - Resource ID.
        args - Arguments for the execute command.
        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • resourceReset

        default void resourceReset​(int iid,
                                   int rid)
                            throws java.lang.Exception
        A handler that shall reset a Resource to its default (after creational) state. In particular, for any writeable optional resource, it shall remove it; for any writeable mandatory Multiple Resource, it shall remove all its instances.

        NOTE: If this handler is not implemented for a Multiple Resource, then non-partial write on it will not succeed.

        NOTE: In the current version of Anjay, this handler is only ever called on Multiple Resources. It is REQUIRED so that after calling this handler, any Multiple Resource is either not PRESENT, or PRESENT, but contain zero Resource Instances.

        Parameters:
        iid - Object Instance ID.
        rid - ID of the Resource to reset.
        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • resourceInstances

        default java.util.SortedSet<java.lang.Integer> resourceInstances​(int iid,
                                                                         int rid)
                                                                  throws java.lang.Exception
        A handler that returns all Resource Instances of a Multiple Resource, called only if the Resource is PRESENT and is of either AnjayObject.ResourceKind.RM, AnjayObject.ResourceKind.WM or AnjayObject.ResourceKind.RWM kind (as returned by resources(int)).
        Parameters:
        iid - Object Instance ID.
        rid - Resource ID.
        Returns:
        SortedSet with Resource Instance IDs.
        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • transactionValidate

        default void transactionValidate()
                                  throws java.lang.Exception
        A handler that is called after transaction is finished, but before transactionCommit() is called. It is used to check whether the commit operation may be successfully performed.

        Any validation of the object's state shall be performed in this function, rather than in the commit handler. If there is a need to commit changes to multiple objects at once, this handler is called on all modified objects first, to avoid potential inconsistencies that may arise from a failing commit operation.

        Successfully returning from this handler means that the corresponding commit function shall subsequently execute successfully. The commit handler may nevertheless fail, but if and only if a fatal, unpredictable and irrecoverable error (e.g. physical write error) occurs.

        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • transactionCommit

        default void transactionCommit()
                                throws java.lang.Exception
        A handler that is called after transaction is finished. If it fails then transactionRollback() handler must be called by the user code if it is necessary.

        NOTE: If this function fails, the data model will be left in an inconsistent state. For this reason, it may return an error value if and only if a fatal, unpredictable and irrecoverable error (e.g. physical write error) occurs. All other errors (such as invalid object state) shall be reported via transactionValidate().

        Throws:
        java.lang.Exception - In case of error. If AnjayException is thrown with one of defined error codes, the response message will have an appropriate CoAP response code. Otherwise, the device will respond with an unspecified (but valid) error code.
      • transactionRollback

        default void transactionRollback()
                                  throws java.lang.Exception
        A handler that is called whenever there is a need to restore previous Object state during a transaction or during committing a transaction.
        Throws:
        java.lang.Exception - In case of error.