org.osgi.service.dmt.notification

Interface NotificationService

public interface NotificationService

NotificationService enables sending asynchronous notifications to a management server. The implementation of NotificationService should register itself in the OSGi service registry as a service.

Method Summary

Methods

Modifier and Type	Method and Description
void	sendNotification(String principal, int code, String correlator, AlertItem[] items) Sends a notification to a named principal.

Method Detail

sendNotification

void sendNotification(String principal,
                    int code,
                    String correlator,
                    AlertItem[] items)
                      throws DmtException

Sends a notification to a named principal. It is the responsibility of the NotificationService to route the notification to the given principal using the registered RemoteAlertSender services.

In remotely initiated sessions the principal name identifies the remote server that created the session, this can be obtained using the session's getPrincipal call.

The principal name may be omitted if the client does not know the principal name. Even in this case the routing might be possible if the Notification Service finds an appropriate default destination (for example if it is only connected to one protocol adapter, which is only connected to one management server).

Since sending the notification and receiving acknowledgment for it is potentially a very time-consuming operation, notifications are sent asynchronously. This method should attempt to ensure that the notification can be sent successfully, and should throw an exception if it detects any problems. If the method returns without error, the notification is accepted for sending and the implementation must make a best-effort attempt to deliver it.

In case the notification is an asynchronous response to a previous execute command, a correlation identifier can be specified to provide the association between the execute and the notification.

In order to send a notification using this method, the caller must have an AlertPermission with a target string matching the specified principal name. If the principal parameter is null (the principal name is not known), the target of the AlertPermission must be "*".

When this method is called with null correlator, null or empty AlertItem array, and a 0 code as values, it should send a protocol specific default notification to initiate a management session. For example, in case of OMA DM this is alert 1201 "Client Initiated Session". The principal parameter can be used to determine the recipient of the session initiation request.

Parameters:

principal - the principal name which is the recipient of this notification, can be null

code - the alert code, can be 0 if not needed

correlator - optional field that contains the correlation identifier of an associated exec command, can be null if not needed

items - the data of the alert items carried in this alert, can be null or empty if not needed

Throws:

DmtException - with the following possible error codes:

• UNAUTHORIZED when the remote server rejected the request due to insufficient authorization
• ALERT_NOT_ROUTED when the alert can not be routed to the given principal
• REMOTE_ERROR in case of communication problems between the device and the destination
• COMMAND_FAILED for unspecified errors encountered while attempting to complete the command
• FEATURE_NOT_SUPPORTED if the underlying management protocol doesn't support asynchronous notifications

SecurityException - if the caller does not have the required AlertPermission with a target matching the principal parameter, as described above