Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * Copyright (c) OSGi Alliance (2004, 2013). All Rights Reserved.
   * 
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package org.osgi.service.dmt;

An interface providing methods to open sessions and register listeners. The implementation of DmtAdmin should register itself in the OSGi service registry as a service. DmtAdmin is the entry point for applications to use the DMT API.

The getSession methods are used to open a session on a specified subtree of the DMT. A typical way of usage:

 serviceRef = context.getServiceReference(DmtAdmin.class.getName());
 DmtAdmin admin = (DmtAdmin) context.getService(serviceRef);
 DmtSession session = admin.getSession("./OSGi/Configuration");
 session.createInteriorNode("./OSGi/Configuration/my.table");
 

The methods for opening a session take a node URI (the session root) as a parameter. All segments of the given URI must be within the segment length limit of the implementation, and the special characters '/' and '\' must be escaped (preceded by a '\').

See the Uri.encode(java.lang.String) method for support on escaping invalid characters in a URI.

It is possible to specify a lock mode when opening the session (see lock type constants in DmtSession). This determines whether the session can run in parallel with other sessions, and the kinds of operations that can be performed in the session. All Management Objects constituting the device management tree must support read operations on their nodes, while support for write operations depends on the Management Object. Management Objects supporting write access may support transactional write, non-transactional write or both. Users of DmtAdmin should consult the Management Object specification and implementation for the supported update modes. If Management Object definition permits, implementations are encouraged to support both update modes.

Author(s):
$Id: 193fb8ed85cf47cdc98b31f0fb1fb11d3bad57eb $
 
 public interface DmtAdmin {

Opens a DmtSession for local usage on a given subtree of the DMT with non transactional write lock. This call is equivalent to the following: getSession(null, subtreeUri, DmtSession.LOCK_TYPE_EXCLUSIVE)

The subtreeUri parameter must contain an absolute URI. It can also be null, in this case the session is opened with the default session root, ".", that gives access to the whole tree.

To perform this operation the caller must have DmtPermission for the subtreeUri node with the Get action present.

Parameters:
subtreeUri the subtree on which DMT manipulations can be performed within the returned session
Returns:
a DmtSession object for the requested subtree
Throws:
DmtException with the following possible error codes:
  • INVALID_URI if subtreeUri is syntactically invalid
  • URI_TOO_LONG if subtreeUri is longer than accepted by the DmtAdmin implementation (especially on systems with limited resources)
  • NODE_NOT_FOUND if subtreeUri specifies a non-existing node
  • SESSION_CREATION_TIMEOUT if the operation timed out because of another ongoing session
  • COMMAND_FAILED if subtreeUri specifies a relative URI, or some unspecified error is encountered while attempting to complete the command
java.lang.SecurityException if the caller does not have DmtPermission for the given root node with the Get action present
 
 	DmtSession getSession(String subtreeUrithrows DmtException;

Opens a DmtSession for local usage on a specific DMT subtree with a given lock mode. This call is equivalent to the following: getSession(null, subtreeUri, lockMode)

The subtreeUri parameter must contain an absolute URI. It can also be null, in this case the session is opened with the default session root, ".", that gives access to the whole tree.

To perform this operation the caller must have DmtPermission for the subtreeUri node with the Get action present.

Parameters:
subtreeUri the subtree on which DMT manipulations can be performed within the returned session
lockMode one of the lock modes specified in DmtSession
Returns:
a DmtSession object for the requested subtree
Throws:
DmtException with the following possible error codes:
  • INVALID_URI if subtreeUri is syntactically invalid
  • URI_TOO_LONG if subtreeUri is longer than accepted by the DmtAdmin implementation (especially on systems with limited resources)
  • NODE_NOT_FOUND if subtreeUri specifies a non-existing node
  • FEATURE_NOT_SUPPORTED if atomic sessions are not supported by the implementation and lockMode requests an atomic session
  • SESSION_CREATION_TIMEOUT if the operation timed out because of another ongoing session
  • COMMAND_FAILED if subtreeUri specifies a relative URI, if lockMode is unknown, or some unspecified error is encountered while attempting to complete the command
java.lang.SecurityException if the caller does not have DmtPermission for the given root node with the Get action present
	DmtSession getSession(String subtreeUriint lockModethrows DmtException;

Opens a DmtSession on a specific DMT subtree using a specific lock mode on behalf of a remote principal. If local management applications are using this method then they should provide null as the first parameter. Alternatively they can use other forms of this method without providing a principal string.

The subtreeUri parameter must contain an absolute URI. It can also be null, in this case the session is opened with the default session root, ".", that gives access to the whole tree.

This method is guarded by DmtPrincipalPermission in case of remote sessions. In addition, the caller must have Get access rights (ACL in case of remote sessions, DmtPermission in case of local sessions) on the subtreeUri node to perform this operation.

Parameters:
principal the identifier of the remote server on whose behalf the data manipulation is performed, or null for local sessions
subtreeUri the subtree on which DMT manipulations can be performed within the returned session
lockMode one of the lock modes specified in DmtSession
Returns:
a DmtSession object for the requested subtree
Throws:
DmtException with the following possible error codes:
  • INVALID_URI if subtreeUri is syntactically invalid
  • URI_TOO_LONG if subtreeUri is longer than accepted by the DmtAdmin implementation (especially on systems with limited resources)
  • NODE_NOT_FOUND if subtreeUri specifies a non-existing node
  • PERMISSION_DENIED if principal is not null and the ACL of the node does not allow the Get operation for the principal on the given root node
  • FEATURE_NOT_SUPPORTED if atomic sessions are not supported by the implementation and lockMode requests an atomic session
  • SESSION_CREATION_TIMEOUT if the operation timed out because of another ongoing session
  • COMMAND_FAILED if subtreeUri specifies a relative URI, if lockMode is unknown, or some unspecified error is encountered while attempting to complete the command
java.lang.SecurityException in case of remote sessions, if the caller does not have the required DmtPrincipalPermission with a target matching the principal parameter, or in case of local sessions, if the caller does not have DmtPermission for the given root node with the Get action present
	DmtSession getSession(String principalString subtreeUriint lockModethrows DmtException;
New to GrepCode? Check out our FAQ X