blob: fd8d692f882d1ed65da2f90e5184320dbccc0b16 [file] [log] [blame]
Christian van Spaandonk63814412008-08-02 09:56:01 +00001/*
Richard S. Hall8df9ab12009-07-24 17:06:37 +00002 * Copyright (c) OSGi Alliance (2004, 2008). All Rights Reserved.
Christian van Spaandonk63814412008-08-02 09:56:01 +00003 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package info.dmtree;
17
18import java.util.Date;
19
20/**
21 * DmtSession provides concurrent access to the DMT. All DMT manipulation
22 * commands for management applications are available on the
Richard S. Hall8df9ab12009-07-24 17:06:37 +000023 * <code>DmtSession</code> interface. The session is associated with a root node
24 * which limits the subtree in which the operations can be executed within this
25 * session.
Christian van Spaandonk63814412008-08-02 09:56:01 +000026 * <p>
27 * Most of the operations take a node URI as parameter, which can be either an
28 * absolute URI (starting with &quot;./&quot;) or a URI relative to the root
29 * node of the session. The empty string as relative URI means the root URI the
30 * session was opened with. All segments of a URI must be within the segment
31 * length limit of the implementation, and the special characters '/' and '\'
32 * must be escaped (preceded by a '\'). Any string can be converted to a valid
33 * URI segment using the {@link Uri#mangle(String)} method.
34 * <p>
35 * If the URI specified does not correspond to a legitimate node in the tree an
36 * exception is thrown. The only exception is the {@link #isNodeUri(String)}
37 * method which returns <code>false</code> in case of an invalid URI.
38 * <p>
Richard S. Hall8df9ab12009-07-24 17:06:37 +000039 * Each method of <code>DmtSession</code> that accesses the tree in any way can
40 * throw <code>DmtIllegalStateException</code> if the session has been closed or
41 * invalidated (due to timeout, fatal exceptions, or unexpectedly unregistered
42 * plugins).
43 *
44 * @version $Revision: 5673 $
Christian van Spaandonk63814412008-08-02 09:56:01 +000045 */
46public interface DmtSession {
47 /**
48 * Sessions created with <code>LOCK_TYPE_SHARED</code> lock allows
49 * read-only access to the tree, but can be shared between multiple readers.
50 */
51 int LOCK_TYPE_SHARED = 0;
52
53 /**
54 * <code>LOCK_TYPE_EXCLUSIVE</code> lock guarantees full access to the
55 * tree, but can not be shared with any other locks.
56 */
57 int LOCK_TYPE_EXCLUSIVE = 1;
58
59 /**
60 * <code>LOCK_TYPE_ATOMIC</code> is an exclusive lock with transactional
61 * functionality. Commands of an atomic session will either fail or succeed
62 * together, if a single command fails then the whole session will be rolled
63 * back.
64 */
65 int LOCK_TYPE_ATOMIC = 2;
66
67 /**
68 * The session is open, all session operations are available.
69 */
70 int STATE_OPEN = 0;
71
72 /**
73 * The session is closed, DMT manipulation operations are not available,
74 * they throw <code>DmtIllegalStateException</code> if tried.
75 */
76 int STATE_CLOSED = 1;
77
78 /**
79 * The session is invalid because a fatal error happened. Fatal errors
80 * include the timeout of the session, any DmtException with the 'fatal'
81 * flag set, or the case when a plugin service is unregistered while in use
82 * by the session. DMT manipulation operations are not available, they throw
83 * <code>DmtIllegalStateException</code> if tried.
84 */
85 int STATE_INVALID = 2;
86
87 /**
88 * Get the current state of this session.
89 *
90 * @return the state of the session, one of {@link #STATE_OPEN},
91 * {@link #STATE_CLOSED} and {@link #STATE_INVALID}
92 */
93 int getState();
94
95 /**
96 * Gives the type of lock the session has.
97 *
98 * @return the lock type of the session, one of {@link #LOCK_TYPE_SHARED},
99 * {@link #LOCK_TYPE_EXCLUSIVE} and {@link #LOCK_TYPE_ATOMIC}
100 */
101 int getLockType();
102
103 /**
104 * Gives the name of the principal on whose behalf the session was created.
105 * Local sessions do not have an associated principal, in this case
106 * <code>null</code> is returned.
107 *
108 * @return the identifier of the remote server that initiated the session,
109 * or <code>null</code> for local sessions
110 */
111 String getPrincipal();
112
113 /**
114 * The unique identifier of the session. The ID is generated automatically,
115 * and it is guaranteed to be unique on a machine.
116 *
117 * @return the session identification number
118 */
119 int getSessionId();
120
121 /**
122 * Get the root URI associated with this session. Gives "<code>.</code>"
123 * if the session was created without specifying a root, which means that
124 * the target of this session is the whole DMT.
125 *
126 * @return the root URI
127 */
128 String getRootUri();
129
130 /**
131 * Commits a series of DMT operations issued in the current atomic session
132 * since the last transaction boundary. Transaction boundaries are the
133 * creation of this object that starts the session, and all subsequent
134 * {@link #commit} and {@link #rollback} calls.
135 * <p>
136 * This method can fail even if all operations were successful. This can
137 * happen due to some multi-node semantic constraints defined by a specific
138 * implementation. For example, node A can be required to always have
139 * children A/B, A/C and A/D. If this condition is broken when
140 * <code>commit()</code> is executed, the method will fail, and throw a
141 * <code>METADATA_MISMATCH</code> exception.
142 * <p>
143 * An error situation can arise due to the lack of a two phase commit
144 * mechanism in the underlying plugins. As an example, if plugin A has
145 * committed successfully but plugin B failed, the whole session must fail,
146 * but there is no way to undo the commit performed by A. To provide
147 * predictable behaviour, the commit operation should continue with the
148 * remaining plugins even after detecting a failure. All exceptions received
149 * from failed commits are aggregated into one
150 * <code>TRANSACTION_ERROR</code> exception thrown by this method.
151 * <p>
152 * In many cases the tree is not the only way to manage a given part of the
153 * system. It may happen that while modifying some nodes in an atomic
154 * session, the underlying settings are modified in parallel outside the
155 * scope of the DMT. If this is detected during commit, an exception with
156 * the code <code>CONCURRENT_ACCESS</code> is thrown.
157 *
158 * @throws DmtException with the following possible error codes:
159 * <ul>
160 * <li><code>METADATA_MISMATCH</code> if the operation failed
161 * because of meta-data restrictions
162 * <li><code>CONCURRENT_ACCESS</code> if it is detected that some
163 * modification has been made outside the scope of the DMT to the
164 * nodes affected in the session's operations
165 * <li><code>TRANSACTION_ERROR</code> if an error occurred during
166 * the commit of any of the underlying plugins
167 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
168 * accessing the data store
169 * <li><code>COMMAND_FAILED</code> if some unspecified error is
170 * encountered while attempting to complete the command
171 * </ul>
172 * @throws DmtIllegalStateException if the session was not opened using the
173 * <code>LOCK_TYPE_ATOMIC</code> lock type, or if the session is
174 * already closed or invalidated
175 * @throws SecurityException if the caller does not have the necessary
176 * permissions to execute the underlying management operation
177 */
178 void commit() throws DmtException;
179
180 /**
181 * Rolls back a series of DMT operations issued in the current atomic
182 * session since the last transaction boundary. Transaction boundaries are
183 * the creation of this object that starts the session, and all subsequent
184 * {@link #commit} and {@link #rollback} calls.
185 *
186 * @throws DmtException with the error code <code>ROLLBACK_FAILED</code>
187 * in case the rollback did not succeed
188 * @throws DmtIllegalStateException if the session was not opened using the
189 * <code>LOCK_TYPE_ATOMIC</code> lock type, or if the session is
190 * already closed or invalidated
191 * @throws SecurityException if the caller does not have the necessary
192 * permissions to execute the underlying management operation
193 */
194 void rollback() throws DmtException;
195
196 /**
197 * Closes a session. If the session was opened with atomic lock mode, the
198 * <code>DmtSession</code> must first persist the changes made to the DMT
199 * by calling <code>commit()</code> on all (transactional) plugins
200 * participating in the session. See the documentation of the
201 * {@link #commit} method for details and possible errors during this
202 * operation.
203 * <p>
204 * The state of the session changes to <code>DmtSession.STATE_CLOSED</code>
205 * if the close operation completed successfully, otherwise it becomes
206 * <code>DmtSession.STATE_INVALID</code>.
207 *
208 * @throws DmtException with the following possible error codes:
209 * <ul>
210 * <li><code>METADATA_MISMATCH</code> in case of atomic sessions,
211 * if the commit operation failed because of meta-data restrictions
212 * <li><code>CONCURRENT_ACCESS</code> in case of atomic sessions,
213 * if the commit operation failed because of some modification
214 * outside the scope of the DMT to the nodes affected in the session
215 * <li><code>TRANSACTION_ERROR</code> in case of atomic sessions,
216 * if an underlying plugin failed to commit
217 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
218 * accessing the data store
219 * <li><code>COMMAND_FAILED</code> if an underlying plugin failed
220 * to close, or if some unspecified error is encountered while
221 * attempting to complete the command
222 * </ul>
223 * @throws DmtIllegalStateException if the session is already closed or
224 * invalidated
225 * @throws SecurityException if the caller does not have the necessary
226 * permissions to execute the underlying management operation
227 */
228 void close() throws DmtException;
229
230 /**
231 * Executes a node. This corresponds to the EXEC operation in OMA DM. This
232 * method cannot be called in a read-only session.
233 * <p>
234 * The semantics of an execute operation and the data parameter it takes
235 * depends on the definition of the managed object on which the command is
236 * issued.
237 *
238 * @param nodeUri the node on which the execute operation is issued
239 * @param data the parameter of the execute operation, can be
240 * <code>null</code>
241 * @throws DmtException with the following possible error codes:
242 * <ul>
243 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
244 * segment of it is too long, or if it has too many segments
245 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
246 * <code>null</code> or syntactically invalid
247 * <li><code>NODE_NOT_FOUND</code> if the node does not exist and
248 * the plugin does not allow executing unexisting nodes
249 * <li><code>PERMISSION_DENIED</code> if the session is
250 * associated with a principal and the ACL of the node does not
251 * allow the <code>Execute</code> operation for the associated
252 * principal
253 * <li><code>METADATA_MISMATCH</code> if the node cannot be
254 * executed according to the meta-data (does not have
255 * <code>MetaNode.CMD_EXECUTE</code> access type)
256 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
257 * accessing the data store
258 * <li><code>COMMAND_FAILED</code> if the URI is not within the
259 * current session's subtree, if no DmtExecPlugin is associated with
260 * the node and the DmtAdmin can not execute the node, or if some
261 * unspecified error is encountered while attempting to complete the
262 * command
263 * </ul>
264 * @throws DmtIllegalStateException if the session was opened using the
265 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
266 * already closed or invalidated
267 * @throws SecurityException if the caller does not have the necessary
268 * permissions to execute the underlying management operation, or,
269 * in case of local sessions, if the caller does not have
270 * <code>DmtPermission</code> for the node with the Exec action
271 * present
272 *
273 * @see #execute(String, String, String)
274 */
275 void execute(String nodeUri, String data) throws DmtException;
276
277 /**
278 * Executes a node, also specifying a correlation ID for use in response
279 * notifications. This operation corresponds to the EXEC command in OMA DM.
280 * This method cannot be called in a read-only session.
281 * <p>
282 * The semantics of an execute operation and the data parameter it takes
283 * depends on the definition of the managed object on which the command is
284 * issued. If a correlation ID is specified, it should be used as the
285 * <code>correlator</code> parameter for notifications sent in response to this
286 * execute operation.
287 *
288 * @param nodeUri the node on which the execute operation is issued
289 * @param correlator an identifier to associate this operation with any
290 * notifications sent in response to it, can be <code>null</code> if not
291 * needed
292 * @param data the parameter of the execute operation, can be
293 * <code>null</code>
294 * @throws DmtException with the following possible error codes:
295 * <ul>
296 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
297 * segment of it is too long, or if it has too many segments
298 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
299 * <code>null</code> or syntactically invalid
300 * <li><code>NODE_NOT_FOUND</code> if the node does not exist and
301 * the plugin does not allow executing unexisting nodes
302 * <li><code>PERMISSION_DENIED</code> if the session is
303 * associated with a principal and the ACL of the node does not
304 * allow the <code>Execute</code> operation for the associated
305 * principal
306 * <li><code>METADATA_MISMATCH</code> if the node cannot be
307 * executed according to the meta-data (does not have
308 * <code>MetaNode.CMD_EXECUTE</code> access type)
309 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
310 * accessing the data store
311 * <li><code>COMMAND_FAILED</code> if the URI is not within the
312 * current session's subtree, if no DmtExecPlugin is associated with
313 * the node, or if some unspecified error is encountered while
314 * attempting to complete the command
315 * </ul>
316 * @throws DmtIllegalStateException if the session was opened using the
317 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
318 * already closed or invalidated
319 * @throws SecurityException if the caller does not have the necessary
320 * permissions to execute the underlying management operation, or,
321 * in case of local sessions, if the caller does not have
322 * <code>DmtPermission</code> for the node with the Exec action
323 * present
324 * @see #execute(String, String)
325 */
326 void execute(String nodeUri, String correlator, String data)
327 throws DmtException;
328
329 /**
330 * Get the Access Control List associated with a given node. The returned
331 * <code>Acl</code> object does not take inheritance into account, it
332 * gives the ACL specifically given to the node.
333 *
334 * @param nodeUri the URI of the node
335 * @return the Access Control List belonging to the node or
336 * <code>null</code> if none defined
337 * @throws DmtException with the following possible error codes:
338 * <ul>
339 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
340 * segment of it is too long, or if it has too many segments
341 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
342 * <code>null</code> or syntactically invalid
343 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
344 * points to a non-existing node
345 * <li><code>PERMISSION_DENIED</code> if the session is
346 * associated with a principal and the ACL of the node does not
347 * allow the <code>Get</code> operation for the associated
348 * principal
349 * <li><code>METADATA_MISMATCH</code> if node information cannot
350 * be retrieved according to the meta-data (the node does not have
351 * <code>MetaNode.CMD_GET</code> access type)
352 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
353 * accessing the data store
354 * <li><code>COMMAND_FAILED</code> if the URI is not within the
355 * current session's subtree, or if some unspecified error is
356 * encountered while attempting to complete the command
357 * </ul>
358 * @throws DmtIllegalStateException if the session is already closed or
359 * invalidated
360 * @throws SecurityException in case of local sessions, if the caller does
361 * not have <code>DmtPermission</code> for the node with the Get
362 * action present
363 * @see #getEffectiveNodeAcl
364 */
365 Acl getNodeAcl(String nodeUri) throws DmtException;
366
367 /**
368 * Gives the Access Control List in effect for a given node. The returned
369 * <code>Acl</code> takes inheritance into account, that is if there is no
370 * ACL defined for the node, it will be derived from the closest ancestor
371 * having an ACL defined.
372 *
373 * @param nodeUri the URI of the node
374 * @return the Access Control List belonging to the node
375 * @throws DmtException with the following possible error codes:
376 * <ul>
377 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
378 * segment of it is too long, or if it has too many segments
379 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
380 * <code>null</code> or syntactically invalid
381 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
382 * points to a non-existing node
383 * <li><code>PERMISSION_DENIED</code> if the session is
384 * associated with a principal and the ACL of the node does not
385 * allow the <code>Get</code> operation for the associated
386 * principal
387 * <li><code>METADATA_MISMATCH</code> if node information cannot
388 * be retrieved according to the meta-data (the node does not have
389 * <code>MetaNode.CMD_GET</code> access type)
390 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
391 * accessing the data store
392 * <li><code>COMMAND_FAILED</code> if the URI is not within the
393 * current session's subtree, or if some unspecified error is
394 * encountered while attempting to complete the command
395 * </ul>
396 * @throws DmtIllegalStateException if the session is already closed or
397 * invalidated
398 * @throws SecurityException in case of local sessions, if the caller does
399 * not have <code>DmtPermission</code> for the node with the Get
400 * action present
401 * @see #getNodeAcl
402 */
403 Acl getEffectiveNodeAcl(String nodeUri) throws DmtException;
404
405 /**
406 * Set the Access Control List associated with a given node. To perform this
407 * operation, the caller needs to have replace rights (<code>Acl.REPLACE</code>
408 * or the corresponding Java permission depending on the session type) as
409 * described below:
410 * <ul>
411 * <li>if <code>nodeUri</code> specifies a leaf node, replace rights are
412 * needed on the parent of the node
413 * <li>if <code>nodeUri</code> specifies an interior node, replace rights
414 * on either the node or its parent are sufficient
415 * </ul>
416 * <p>
417 * If the given <code>acl</code> is <code>null</code> or an empty ACL
418 * (not specifying any permissions for any principals), then the ACL of the
419 * node is deleted, and the node will inherit the ACL from its parent node.
420 *
421 * @param nodeUri the URI of the node
422 * @param acl the Access Control List to be set on the node, can be
423 * <code>null</code>
424 * @throws DmtException with the following possible error codes:
425 * <ul>
426 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
427 * segment of it is too long, or if it has too many segments
428 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
429 * <code>null</code> or syntactically invalid
430 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
431 * points to a non-existing node
432 * <li><code>PERMISSION_DENIED</code> if the session is
433 * associated with a principal and the ACL of the node or its parent
434 * (see above) does not allow the <code>Replace</code> operation
435 * for the associated principal
436 * <li><code>COMMAND_NOT_ALLOWED</code> if the command attempts
437 * to set the ACL of the root node not to include Add rights for all
438 * principals
439 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
440 * accessing the data store
441 * <li><code>COMMAND_FAILED</code> if the URI is not within the
442 * current session's subtree, or if some unspecified error is
443 * encountered while attempting to complete the command
444 * </ul>
445 * @throws DmtIllegalStateException if the session was opened using the
446 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
447 * already closed or invalidated
448 * @throws SecurityException in case of local sessions, if the caller does
449 * not have <code>DmtPermission</code> for the node or its parent
450 * (see above) with the Replace action present
451 */
452 void setNodeAcl(String nodeUri, Acl acl) throws DmtException;
453
454 /**
455 * Create a copy of a node or a whole subtree. Beside the structure and
456 * values of the nodes, most properties are also copied, with the exception
457 * of the ACL (Access Control List), Timestamp and Version properties.
458 * <p>
459 * The copy method is essentially a convenience method that could be
460 * substituted with a sequence of retrieval and update operations. This
461 * determines the permissions required for copying. However, some
462 * optimization can be possible if the source and target nodes are all
463 * handled by DmtAdmin or by the same plugin. In this case, the handler
464 * might be able to perform the underlying management operation more
465 * efficiently: for example, a configuration table can be copied at once
466 * instead of reading each node for each entry and creating it in the new
467 * tree.
468 * <p>
469 * This method may result in any of the errors possible for the contributing
470 * operations. Most of these are collected in the exception descriptions
471 * below, but for the full list also consult the documentation of
472 * {@link #getChildNodeNames(String)}, {@link #isLeafNode(String)},
473 * {@link #getNodeValue(String)}, {@link #getNodeType(String)},
474 * {@link #getNodeTitle(String)}, {@link #setNodeTitle(String, String)},
475 * {@link #createLeafNode(String, DmtData, String)} and
476 * {@link #createInteriorNode(String, String)}.
477 *
478 * @param nodeUri the node or root of a subtree to be copied
479 * @param newNodeUri the URI of the new node or root of a subtree
480 * @param recursive <code>false</code> if only a single node is copied,
481 * <code>true</code> if the whole subtree is copied
482 * @throws DmtException with the following possible error codes:
483 * <ul>
484 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or
485 * <code>newNodeUri</code> or any segment of them is too long, or
486 * if they have too many segments
487 * <li><code>INVALID_URI</code> if <code>nodeUri</code> or
488 * <code>newNodeUri</code> is <code>null</code> or syntactically
489 * invalid
490 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
491 * points to a non-existing node, or if <code>newNodeUri</code>
492 * points to a node that cannot exist in the tree according to the
493 * meta-data (see {@link #getMetaNode(String)})
494 * <li><code>NODE_ALREADY_EXISTS</code> if
495 * <code>newNodeUri</code> points to a node that already exists
496 * <li><code>PERMISSION_DENIED</code> if the session is
497 * associated with a principal and the ACL of the copied node(s)
498 * does not allow the <code>Get</code> operation, or the ACL of
499 * the parent of the target node does not allow the <code>Add</code>
500 * operation for the associated principal
501 * <li><code>COMMAND_NOT_ALLOWED</code> if <code>nodeUri</code>
502 * is an ancestor of <code>newNodeUri</code>, or if any of the
503 * implied retrieval or update operations are not allowed
504 * <li><code>METADATA_MISMATCH</code> if any of the meta-data
505 * constraints of the implied retrieval or update operations are
506 * violated
507 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
508 * underlying plugin is read-only or does not support atomic writing
509 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
510 * accessing the data store
511 * <li><code>COMMAND_FAILED</code> if either URI is not within
512 * the current session's subtree, or if some unspecified error is
513 * encountered while attempting to complete the command
514 * </ul>
515 * @throws DmtIllegalStateException if the session was opened using the
516 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
517 * already closed or invalidated
518 * @throws SecurityException if the caller does not have the necessary
519 * permissions to execute the underlying management operation, or,
520 * in case of local sessions, if the caller does not have
521 * <code>DmtPermission</code> for the copied node(s) with the Get
522 * action present, or for the parent of the target node with the Add
523 * action
524 */
525 void copy(String nodeUri, String newNodeUri, boolean recursive)
526 throws DmtException;
527
528 /**
529 * Create an interior node. If the parent node does not exist, it is created
530 * automatically, as if this method were called for the parent URI. This way
531 * all missing ancestor nodes leading to the specified node are created. Any
532 * exceptions encountered while creating the ancestors are propagated to the
533 * caller of this method, these are not explicitly listed in the error
534 * descriptions below.
535 * <p>
536 * If meta-data is available for the node, several checks are made before
537 * creating it. The node must have <code>MetaNode.CMD_ADD</code> access
538 * type, it must be defined as a non-permanent interior node, the node name
539 * must conform to the valid names, and the creation of the new node must
540 * not cause the maximum occurrence number to be exceeded.
541 * <p>
542 * If the meta-data cannot be retrieved because the given node cannot
543 * possibly exist in the tree (it is not defined in the specification), the
544 * <code>NODE_NOT_FOUND</code> error code is returned (see
545 * {@link #getMetaNode(String)}).
546 *
547 * @param nodeUri the URI of the node to create
548 * @throws DmtException with the following possible error codes:
549 * <ul>
550 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
551 * segment of it is too long, or if it has too many segments
552 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
553 * <code>null</code> or syntactically invalid
554 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
555 * points to a node that cannot exist in the tree (see above)
556 * <li><code>NODE_ALREADY_EXISTS</code> if <code>nodeUri</code>
557 * points to a node that already exists
558 * <li><code>PERMISSION_DENIED</code> if the session is
559 * associated with a principal and the ACL of the parent node does
560 * not allow the <code>Add</code> operation for the associated
561 * principal
562 * <li><code>COMMAND_NOT_ALLOWED</code> if the parent node is not
563 * an interior node, or in non-atomic sessions if the underlying
564 * plugin is read-only or does not support non-atomic writing
565 * <li><code>METADATA_MISMATCH</code> if the node could not be
566 * created because of meta-data restrictions (see above)
567 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
568 * underlying plugin is read-only or does not support atomic writing
569 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
570 * accessing the data store
571 * <li><code>COMMAND_FAILED</code> if the URI is not within the
572 * current session's subtree, or if some unspecified error is
573 * encountered while attempting to complete the command
574 * </ul>
575 * @throws DmtIllegalStateException if the session was opened using the
576 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
577 * already closed or invalidated
578 * @throws SecurityException if the caller does not have the necessary
579 * permissions to execute the underlying management operation, or,
580 * in case of local sessions, if the caller does not have
581 * <code>DmtPermission</code> for the parent node with the Add
582 * action present
583 */
584 void createInteriorNode(String nodeUri) throws DmtException;
585
586 /**
587 * Create an interior node with a given type. The type of interior node, if
588 * specified, is a URI identifying a DDF document. If the parent node does
589 * not exist, it is created automatically, as if
590 * {@link #createInteriorNode(String)} were called for the parent URI. This
591 * way all missing ancestor nodes leading to the specified node are created.
592 * Any exceptions encountered while creating the ancestors are propagated to
593 * the caller of this method, these are not explicitly listed in the error
594 * descriptions below.
595 * <p>
596 * If meta-data is available for the node, several checks are made before
597 * creating it. The node must have <code>MetaNode.CMD_ADD</code> access
598 * type, it must be defined as a non-permanent interior node, the node name
599 * must conform to the valid names, and the creation of the new node must
600 * not cause the maximum occurrence number to be exceeded.
601 * <p>
602 * If the meta-data cannot be retrieved because the given node cannot
603 * possibly exist in the tree (it is not defined in the specification), the
604 * <code>NODE_NOT_FOUND</code> error code is returned (see
605 * {@link #getMetaNode(String)}).
606 * <p>
607 * Interior node type identifiers must follow the format defined in section
608 * 7.7.7.2 of the OMA Device Management Tree and Description document.
609 * Checking the validity of the type string does not have to be done by the
610 * DmtAdmin, this can be left to the plugin handling the node (if any), to
611 * avoid unnecessary double-checks.
612 *
613 * @param nodeUri the URI of the node to create
614 * @param type the type URI of the interior node, can be <code>null</code>
615 * if no node type is defined
616 * @throws DmtException with the following possible error codes:
617 * <ul>
618 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
619 * segment of it is too long, or if it has too many segments
620 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
621 * <code>null</code> or syntactically invalid
622 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
623 * points to a node that cannot exist in the tree (see above)
624 * <li><code>NODE_ALREADY_EXISTS</code> if <code>nodeUri</code>
625 * points to a node that already exists
626 * <li><code>PERMISSION_DENIED</code> if the session is
627 * associated with a principal and the ACL of the parent node does
628 * not allow the <code>Add</code> operation for the associated
629 * principal
630 * <li><code>COMMAND_NOT_ALLOWED</code> if the parent node is not
631 * an interior node, or in non-atomic sessions if the underlying
632 * plugin is read-only or does not support non-atomic writing
633 * <li><code>METADATA_MISMATCH</code> if the node could not be
634 * created because of meta-data restrictions (see above)
635 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
636 * underlying plugin is read-only or does not support atomic writing
637 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
638 * accessing the data store
639 * <li><code>COMMAND_FAILED</code> if the URI is not within the
640 * current session's subtree, if the type string is invalid (see
641 * above), or if some unspecified error is encountered while
642 * attempting to complete the command
643 * </ul>
644 * @throws DmtIllegalStateException if the session was opened using the
645 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
646 * already closed or invalidated
647 * @throws SecurityException if the caller does not have the necessary
648 * permissions to execute the underlying management operation, or,
649 * in case of local sessions, if the caller does not have
650 * <code>DmtPermission</code> for the parent node with the Add
651 * action present
652 * @see #createInteriorNode(String)
653 * @see <a
654 * href="http://member.openmobilealliance.org/ftp/public_documents/dm/Permanent_documents/OMA-TS-DM-TND-V1_2-20050615-C.zip">
655 * OMA Device Management Tree and Description v1.2 draft</a>
656 */
657 void createInteriorNode(String nodeUri, String type) throws DmtException;
658
659 /**
660 * Create a leaf node with default value and MIME type. If a node does not
661 * have a default value or MIME type, this method will throw a
662 * <code>DmtException</code> with error code
663 * <code>METADATA_MISMATCH</code>. Note that a node might have a default
664 * value or MIME type even if there is no meta-data for the node or its
665 * meta-data does not specify the default.
666 * <p>
667 * If the parent node does not exist, it is created automatically, as if
668 * {@link #createInteriorNode(String)} were called for the parent URI. This
669 * way all missing ancestor nodes leading to the specified node are created.
670 * Any exceptions encountered while creating the ancestors are propagated to
671 * the caller of this method, these are not explicitly listed in the error
672 * descriptions below.
673 * <p>
674 * If meta-data is available for a node, several checks are made before
675 * creating it. The node must have <code>MetaNode.CMD_ADD</code> access
676 * type, it must be defined as a non-permanent leaf node, the node name must
677 * conform to the valid names, and the creation of the new node must not
678 * cause the maximum occurrence number to be exceeded.
679 * <p>
680 * If the meta-data cannot be retrieved because the given node cannot
681 * possibly exist in the tree (it is not defined in the specification), the
682 * <code>NODE_NOT_FOUND</code> error code is returned (see
683 * {@link #getMetaNode(String)}).
684 *
685 * @param nodeUri the URI of the node to create
686 * @throws DmtException with the following possible error codes:
687 * <ul>
688 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
689 * segment of it is too long, or if it has too many segments
690 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
691 * <code>null</code> or syntactically invalid
692 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
693 * points to a node that cannot exist in the tree (see above)
694 * <li><code>NODE_ALREADY_EXISTS</code> if <code>nodeUri</code>
695 * points to a node that already exists
696 * <li><code>PERMISSION_DENIED</code> if the session is
697 * associated with a principal and the ACL of the parent node does
698 * not allow the <code>Add</code> operation for the associated
699 * principal
700 * <li><code>COMMAND_NOT_ALLOWED</code> if the parent node is not
701 * an interior node, or in non-atomic sessions if the underlying
702 * plugin is read-only or does not support non-atomic writing
703 * <li><code>METADATA_MISMATCH</code> if the node could not be
704 * created because of meta-data restrictions (see above)
705 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
706 * underlying plugin is read-only or does not support atomic writing
707 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
708 * accessing the data store
709 * <li><code>COMMAND_FAILED</code> if the URI is not within the
710 * current session's subtree, or if some unspecified error is
711 * encountered while attempting to complete the command
712 * </ul>
713 * @throws DmtIllegalStateException if the session was opened using the
714 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
715 * already closed or invalidated
716 * @throws SecurityException if the caller does not have the necessary
717 * permissions to execute the underlying management operation, or,
718 * in case of local sessions, if the caller does not have
719 * <code>DmtPermission</code> for the parent node with the Add
720 * action present
721 * @see #createLeafNode(String, DmtData)
722 */
723 void createLeafNode(String nodeUri) throws DmtException;
724
725 /**
726 * Create a leaf node with a given value and the default MIME type. If the
727 * specified value is <code>null</code>, the default value is taken. If
728 * the node does not have a default MIME type or value (if needed), this
729 * method will throw a <code>DmtException</code> with error code
730 * <code>METADATA_MISMATCH</code>. Note that a node might have a default
731 * value or MIME type even if there is no meta-data for the node or its
732 * meta-data does not specify the default.
733 * <p>
734 * If the parent node does not exist, it is created automatically, as if
735 * {@link #createInteriorNode(String)} were called for the parent URI. This
736 * way all missing ancestor nodes leading to the specified node are created.
737 * Any exceptions encountered while creating the ancestors are propagated to
738 * the caller of this method, these are not explicitly listed in the error
739 * descriptions below.
740 * <p>
741 * If meta-data is available for a node, several checks are made before
742 * creating it. The node must have <code>MetaNode.CMD_ADD</code> access
743 * type, it must be defined as a non-permanent leaf node, the node name must
744 * conform to the valid names, the node value must conform to the value
745 * constraints, and the creation of the new node must not cause the maximum
746 * occurrence number to be exceeded.
747 * <p>
748 * If the meta-data cannot be retrieved because the given node cannot
749 * possibly exist in the tree (it is not defined in the specification), the
750 * <code>NODE_NOT_FOUND</code> error code is returned (see
751 * {@link #getMetaNode(String)}).
752 * <p>
753 * Nodes of <code>null</code> format can be created by using
754 * {@link DmtData#NULL_VALUE} as second argument.
755 *
756 * @param nodeUri the URI of the node to create
757 * @param value the value to be given to the new node, can be
758 * <code>null</code>
759 * @throws DmtException with the following possible error codes:
760 * <ul>
761 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
762 * segment of it is too long, or if it has too many segments
763 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
764 * <code>null</code> or syntactically invalid
765 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
766 * points to a node that cannot exist in the tree (see above)
767 * <li><code>NODE_ALREADY_EXISTS</code> if <code>nodeUri</code>
768 * points to a node that already exists
769 * <li><code>PERMISSION_DENIED</code> if the session is
770 * associated with a principal and the ACL of the parent node does
771 * not allow the <code>Add</code> operation for the associated
772 * principal
773 * <li><code>COMMAND_NOT_ALLOWED</code> if the parent node is not
774 * an interior node, or in non-atomic sessions if the underlying
775 * plugin is read-only or does not support non-atomic writing
776 * <li><code>METADATA_MISMATCH</code> if the node could not be
777 * created because of meta-data restrictions (see above)
778 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
779 * underlying plugin is read-only or does not support atomic writing
780 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
781 * accessing the data store
782 * <li><code>COMMAND_FAILED</code> if the URI is not within the
783 * current session's subtree, or if some unspecified error is
784 * encountered while attempting to complete the command
785 * </ul>
786 * @throws DmtIllegalStateException if the session was opened using the
787 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
788 * already closed or invalidated
789 * @throws SecurityException if the caller does not have the necessary
790 * permissions to execute the underlying management operation, or,
791 * in case of local sessions, if the caller does not have
792 * <code>DmtPermission</code> for the parent node with the Add
793 * action present
794 */
795 void createLeafNode(String nodeUri, DmtData value) throws DmtException;
796
797 /**
798 * Create a leaf node with a given value and MIME type. If the specified
799 * value or MIME type is <code>null</code>, their default values are
800 * taken. If the node does not have the necessary defaults, this method will
801 * throw a <code>DmtException</code> with error code
802 * <code>METADATA_MISMATCH</code>. Note that a node might have a default
803 * value or MIME type even if there is no meta-data for the node or its
804 * meta-data does not specify the default.
805 * <p>
806 * If the parent node does not exist, it is created automatically, as if
807 * {@link #createInteriorNode(String)} were called for the parent URI. This
808 * way all missing ancestor nodes leading to the specified node are created.
809 * Any exceptions encountered while creating the ancestors are propagated to
810 * the caller of this method, these are not explicitly listed in the error
811 * descriptions below.
812 * <p>
813 * If meta-data is available for a node, several checks are made before
814 * creating it. The node must have <code>MetaNode.CMD_ADD</code> access
815 * type, it must be defined as a non-permanent leaf node, the node name must
816 * conform to the valid names, the node value must conform to the value
817 * constraints, the MIME type must be among the listed types, and the
818 * creation of the new node must not cause the maximum occurrence number to
819 * be exceeded.
820 * <p>
821 * If the meta-data cannot be retrieved because the given node cannot
822 * possibly exist in the tree (it is not defined in the specification), the
823 * <code>NODE_NOT_FOUND</code> error code is returned (see
824 * {@link #getMetaNode(String)}).
825 * <p>
826 * Nodes of <code>null</code> format can be created by using
827 * {@link DmtData#NULL_VALUE} as second argument.
828 * <p>
829 * The MIME type string must conform to the definition in RFC 2045. Checking
830 * its validity does not have to be done by the DmtAdmin, this can be left
831 * to the plugin handling the node (if any), to avoid unnecessary
832 * double-checks.
833 *
834 * @param nodeUri the URI of the node to create
835 * @param value the value to be given to the new node, can be
836 * <code>null</code>
837 * @param mimeType the MIME type to be given to the new node, can be
838 * <code>null</code>
839 * @throws DmtException with the following possible error codes:
840 * <ul>
841 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
842 * segment of it is too long, or if it has too many segments
843 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
844 * <code>null</code> or syntactically invalid
845 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
846 * points to a node that cannot exist in the tree (see above)
847 * <li><code>NODE_ALREADY_EXISTS</code> if <code>nodeUri</code>
848 * points to a node that already exists
849 * <li><code>PERMISSION_DENIED</code> if the session is
850 * associated with a principal and the ACL of the parent node does
851 * not allow the <code>Add</code> operation for the associated
852 * principal
853 * <li><code>COMMAND_NOT_ALLOWED</code> if the parent node is not
854 * an interior node, or in non-atomic sessions if the underlying
855 * plugin is read-only or does not support non-atomic writing
856 * <li><code>METADATA_MISMATCH</code> if the node could not be
857 * created because of meta-data restrictions (see above)
858 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
859 * underlying plugin is read-only or does not support atomic writing
860 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
861 * accessing the data store
862 * <li><code>COMMAND_FAILED</code> if the URI is not within the
863 * current session's subtree, if <code>mimeType</code> is not a
864 * proper MIME type string (see above), or if some unspecified error
865 * is encountered while attempting to complete the command
866 * </ul>
867 * @throws DmtIllegalStateException if the session was opened using the
868 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
869 * already closed or invalidated
870 * @throws SecurityException if the caller does not have the necessary
871 * permissions to execute the underlying management operation, or,
872 * in case of local sessions, if the caller does not have
873 * <code>DmtPermission</code> for the parent node with the Add
874 * action present
875 * @see #createLeafNode(String, DmtData)
876 * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>
877 */
878 void createLeafNode(String nodeUri, DmtData value, String mimeType)
879 throws DmtException;
880
881 /**
882 * Delete the given node. Deleting interior nodes is recursive, the whole
883 * subtree under the given node is deleted. It is not allowed to delete
884 * the root node of the session.
885 * <p>
886 * If meta-data is available for a node, several checks are made before
887 * deleting it. The node must be non-permanent, it must have the
888 * <code>MetaNode.CMD_DELETE</code> access type, and if zero occurrences
889 * of the node are not allowed, it must not be the last one.
890 *
891 * @param nodeUri the URI of the node
892 * @throws DmtException with the following possible error codes:
893 * <ul>
894 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
895 * segment of it is too long, or if it has too many segments
896 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
897 * <code>null</code> or syntactically invalid
898 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
899 * points to a non-existing node
900 * <li><code>PERMISSION_DENIED</code> if the session is
901 * associated with a principal and the ACL of the node does not
902 * allow the <code>Delete</code> operation for the associated
903 * principal
904 * <li><code>COMMAND_NOT_ALLOWED</code> if the target node is the
905 * root of the session, or in non-atomic sessions if the underlying
906 * plugin is read-only or does not support non-atomic writing
907 * <li><code>METADATA_MISMATCH</code> if the node could not be
908 * deleted because of meta-data restrictions (see above)
909 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
910 * underlying plugin is read-only or does not support atomic writing
911 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
912 * accessing the data store
913 * <li><code>COMMAND_FAILED</code> if the URI is not within the
914 * current session's subtree, or if some unspecified error is
915 * encountered while attempting to complete the command
916 * </ul>
917 * @throws DmtIllegalStateException if the session was opened using the
918 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
919 * already closed or invalidated
920 * @throws SecurityException if the caller does not have the necessary
921 * permissions to execute the underlying management operation, or,
922 * in case of local sessions, if the caller does not have
923 * <code>DmtPermission</code> for the node with the Delete action
924 * present
925 */
926 void deleteNode(String nodeUri) throws DmtException;
927
928 /**
929 * Rename a node. This operation only changes the name of the node (updating
930 * the timestamp and version properties if they are supported), the value
931 * and the other properties are not changed. The new name of the node must
932 * be provided, the new URI is constructed from the base of the old URI and
933 * the given name. It is not allowed to rename the root node of the session.
934 * <p>
935 * If available, the meta-data of the original and the new nodes are checked
936 * before performing the rename operation. Neither node can be permanent,
937 * their leaf/interior property must match, and the name change must not
938 * violate any of the cardinality constraints. The original node must have
939 * the <code>MetaNode.CMD_REPLACE</code> access type, and the name of the
940 * new node must conform to the valid names.
941 *
942 * @param nodeUri the URI of the node to rename
943 * @param newName the new name property of the node
944 * @throws DmtException with the following possible error codes:
945 * <ul>
946 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
947 * segment of it is too long, if <code>nodeUri</code> has too many
948 * segments, or if <code>newName</code> is too long
949 * <li><code>INVALID_URI</code> if <code>nodeUri</code> or
950 * <code>newName</code> is <code>null</code> or syntactically
951 * invalid
952 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
953 * points to a non-existing node, or if the new node is not defined
954 * in the tree according to the meta-data (see
955 * {@link #getMetaNode(String)})
956 * <li><code>NODE_ALREADY_EXISTS</code> if there already exists a
957 * sibling of <code>nodeUri</code> with the name
958 * <code>newName</code>
959 * <li><code>PERMISSION_DENIED</code> if the session is
960 * associated with a principal and the ACL of the node does not
961 * allow the <code>Replace</code> operation for the associated
962 * principal
963 * <li><code>COMMAND_NOT_ALLOWED</code> if the target node is the
964 * root of the session, or in non-atomic sessions if the underlying
965 * plugin is read-only or does not support non-atomic writing
966 * <li><code>METADATA_MISMATCH</code> if the node could not be
967 * renamed because of meta-data restrictions (see above)
968 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
969 * underlying plugin is read-only or does not support atomic writing
970 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
971 * accessing the data store
972 * <li><code>COMMAND_FAILED</code> if the URI is not within the
973 * current session's subtree, or if some unspecified error is
974 * encountered while attempting to complete the command
975 * </ul>
976 * @throws DmtIllegalStateException if the session was opened using the
977 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
978 * already closed or invalidated
979 * @throws SecurityException if the caller does not have the necessary
980 * permissions to execute the underlying management operation, or,
981 * in case of local sessions, if the caller does not have
982 * <code>DmtPermission</code> for the node with the Replace action
983 * present
984 */
985 void renameNode(String nodeUri, String newName) throws DmtException;
986
987 /**
988 * Set the value of a leaf or interior node to its default. The default
989 * can be defined by the node's <code>MetaNode</code>. The method throws a
990 * <code>METADATA_MISMATCH</code> exception if the node does not have a
991 * default value.
992 *
993 * @param nodeUri the URI of the node
994 * @throws DmtException with the following possible error codes:
995 * <ul>
996 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
997 * segment of it is too long, or if it has too many segments
998 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
999 * <code>null</code> or syntactically invalid
1000 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1001 * points to a non-existing node
1002 * <li><code>PERMISSION_DENIED</code> if the session is
1003 * associated with a principal and the ACL of the node does not
1004 * allow the <code>Replace</code> operation for the associated
1005 * principal
1006 * <li><code>COMMAND_NOT_ALLOWED</code> in non-atomic sessions if
1007 * the underlying plugin is read-only or does not support non-atomic
1008 * writing
1009 * <li><code>METADATA_MISMATCH</code> if the node is permanent or
1010 * cannot be modified according to the meta-data (does not have the
1011 * <code>MetaNode.CMD_REPLACE</code> access type), or if there is
1012 * no default value defined for this node
1013 * <li><code>FEATURE_NOT_SUPPORTED</code> if the specified node is
1014 * an interior node and does not support Java object values
1015 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
1016 * underlying plugin is read-only or does not support atomic writing
1017 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1018 * accessing the data store
1019 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1020 * current session's subtree, or if some unspecified error is
1021 * encountered while attempting to complete the command
1022 * </ul>
1023 * @throws DmtIllegalStateException if the session was opened using the
1024 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
1025 * already closed or invalidated
1026 * @throws SecurityException if the caller does not have the necessary
1027 * permissions to execute the underlying management operation, or,
1028 * in case of local sessions, if the caller does not have
1029 * <code>DmtPermission</code> for the node with the Replace action
1030 * present
1031 * @see #setNodeValue
1032 */
1033 void setDefaultNodeValue(String nodeUri) throws DmtException;
1034
1035 /**
1036 * Set the value of a leaf or interior node. The format of the node is
1037 * contained in the <code>DmtData</code> object. For interior nodes, the
1038 * format must be <code>FORMAT_NODE</code>, while for leaf nodes this
1039 * format must not be used.
1040 * <p>
1041 * If the specified value is <code>null</code>, the default value is taken.
1042 * In this case, if the node does not have a default value, this method will
1043 * throw a <code>DmtException</code> with error code
1044 * <code>METADATA_MISMATCH</code>. Nodes of <code>null</code> format can be
1045 * set by using {@link DmtData#NULL_VALUE} as second argument.
1046 * <p>
1047 * An Event of type REPLACE is sent out for a leaf node. A replaced interior
1048 * node sends out events for each of its children in depth first order
1049 * and node names sorted with Arrays.sort(String[]). When setting a value
1050 * on an interior node, the values of the leaf nodes under it can change,
1051 * but the structure of the subtree is not modified by the operation.
1052 *
1053 * @param nodeUri the URI of the node
1054 * @param data the data to be set, can be <code>null</code>
1055 * @throws DmtException with the following possible error codes:
1056 * <ul>
1057 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1058 * segment of it is too long, or if it has too many segments
1059 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1060 * <code>null</code> or syntactically invalid
1061 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1062 * points to a non-existing node
1063 * <li><code>PERMISSION_DENIED</code> if the session is
1064 * associated with a principal and the ACL of the node does not
1065 * allow the <code>Replace</code> operation for the associated
1066 * principal
1067 * <li><code>COMMAND_NOT_ALLOWED</code> if the given data has
1068 * <code>FORMAT_NODE</code> format but the node is a leaf node (or
1069 * vice versa), or in non-atomic sessions if the underlying plugin
1070 * is read-only or does not support non-atomic writing
1071 * <li><code>METADATA_MISMATCH</code> if the node is permanent or
1072 * cannot be modified according to the meta-data (does not have the
1073 * <code>MetaNode.CMD_REPLACE</code> access type), or if the given
1074 * value does not conform to the meta-data value constraints
1075 * <li><code>FEATURE_NOT_SUPPORTED</code> if the specified node is
1076 * an interior node and does not support Java object values
1077 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
1078 * underlying plugin is read-only or does not support atomic writing
1079 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1080 * accessing the data store
1081 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1082 * current session's subtree, or if some unspecified error is
1083 * encountered while attempting to complete the command
1084 * </ul>
1085 * @throws DmtIllegalStateException if the session was opened using the
1086 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
1087 * already closed or invalidated
1088 * @throws SecurityException if the caller does not have the necessary
1089 * permissions to execute the underlying management operation, or,
1090 * in case of local sessions, if the caller does not have
1091 * <code>DmtPermission</code> for the node with the Replace action
1092 * present
1093 */
1094 void setNodeValue(String nodeUri, DmtData data) throws DmtException;
1095
1096 /**
1097 * Set the title property of a node. The length of the title string in UTF-8
1098 * encoding must not exceed 255 bytes.
1099 *
1100 * @param nodeUri the URI of the node
1101 * @param title the title text of the node, can be <code>null</code>
1102 * @throws DmtException with the following possible error codes:
1103 * <ul>
1104 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1105 * segment of it is too long, or if it has too many segments
1106 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1107 * <code>null</code> or syntactically invalid
1108 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1109 * points to a non-existing node
1110 * <li><code>PERMISSION_DENIED</code> if the session is
1111 * associated with a principal and the ACL of the node does not
1112 * allow the <code>Replace</code> operation for the associated
1113 * principal
1114 * <li><code>COMMAND_NOT_ALLOWED</code> in non-atomic sessions if
1115 * the underlying plugin is read-only or does not support non-atomic
1116 * writing
1117 * <li><code>METADATA_MISMATCH</code> if the node cannot be
1118 * modified according to the meta-data (does not have the
1119 * <code>MetaNode.CMD_REPLACE</code> access type)
1120 * <li><code>FEATURE_NOT_SUPPORTED</code> if the Title property
1121 * is not supported by the DmtAdmin implementation or the
1122 * underlying plugin
1123 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
1124 * underlying plugin is read-only or does not support atomic writing
1125 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1126 * accessing the data store
1127 * <li><code>COMMAND_FAILED</code> if the title string is too
1128 * long, if the URI is not within the current session's subtree, or
1129 * if some unspecified error is encountered while attempting to
1130 * complete the command
1131 * </ul>
1132 * @throws DmtIllegalStateException if the session was opened using the
1133 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
1134 * already closed or invalidated
1135 * @throws SecurityException if the caller does not have the necessary
1136 * permissions to execute the underlying management operation, or,
1137 * in case of local sessions, if the caller does not have
1138 * <code>DmtPermission</code> for the node with the Replace action
1139 * present
1140 */
1141 void setNodeTitle(String nodeUri, String title) throws DmtException;
1142
1143 /**
1144 * Set the type of a node. The type of leaf node is the MIME type of the
1145 * data it contains. The type of an interior node is a URI identifying a DDF
1146 * document.
1147 * <p>
1148 * For interior nodes, a <code>null</code> type string means that there is
1149 * no DDF document overriding the tree structure defined by the ancestors.
1150 * For leaf nodes, it requests that the default MIME type is used for the
1151 * given node. If the node does not have a default MIME type this method
1152 * will throw a <code>DmtException</code> with error code
1153 * <code>METADATA_MISMATCH</code>. Note that a node might have a default
1154 * MIME type even if there is no meta-data for the node or its meta-data
1155 * does not specify the default.
1156 * <p>
1157 * MIME types must conform to the definition in RFC 2045. Interior node type
1158 * identifiers must follow the format defined in section 7.7.7.2 of the OMA
1159 * Device Management Tree and Description document. Checking the validity of
1160 * the type string does not have to be done by the DmtAdmin, this can be
1161 * left to the plugin handling the node (if any), to avoid unnecessary
1162 * double-checks.
1163 *
1164 * @param nodeUri the URI of the node
1165 * @param type the type of the node, can be <code>null</code>
1166 * @throws DmtException with the following possible error codes:
1167 * <ul>
1168 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1169 * segment of it is too long, or if it has too many segments
1170 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1171 * <code>null</code> or syntactically invalid
1172 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1173 * points to a non-existing node
1174 * <li><code>PERMISSION_DENIED</code> if the session is
1175 * associated with a principal and the ACL of the node does not
1176 * allow the <code>Replace</code> operation for the associated
1177 * principal
1178 * <li><code>COMMAND_NOT_ALLOWED</code> in non-atomic sessions if
1179 * the underlying plugin is read-only or does not support non-atomic
1180 * writing
1181 * <li><code>METADATA_MISMATCH</code> if the node is permanent or
1182 * cannot be modified according to the meta-data (does not have the
1183 * <code>MetaNode.CMD_REPLACE</code> access type), and in case of
1184 * leaf nodes, if <code>null</code> is given and there is no
1185 * default MIME type, or the given MIME type is not allowed
1186 * <li><code>TRANSACTION_ERROR</code> in an atomic session if the
1187 * underlying plugin is read-only or does not support atomic writing
1188 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1189 * accessing the data store
1190 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1191 * current session's subtree, if the type string is invalid (see
1192 * above), or if some unspecified error is encountered while
1193 * attempting to complete the command
1194 * </ul>
1195 * @throws DmtIllegalStateException if the session was opened using the
1196 * <code>LOCK_TYPE_SHARED</code> lock type, or if the session is
1197 * already closed or invalidated
1198 * @throws SecurityException if the caller does not have the necessary
1199 * permissions to execute the underlying management operation, or,
1200 * in case of local sessions, if the caller does not have
1201 * <code>DmtPermission</code> for the node with the Replace action
1202 * present
1203 * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>
1204 * @see <a
1205 * href="http://member.openmobilealliance.org/ftp/public_documents/dm/Permanent_documents/OMA-TS-DM-TND-V1_2-20050615-C.zip">
1206 * OMA Device Management Tree and Description v1.2 draft</a>
1207 */
1208 void setNodeType(String nodeUri, String type) throws DmtException;
1209
1210 /**
1211 * Get the list of children names of a node. The returned array contains the
1212 * names - not the URIs - of the immediate children nodes of the given node.
Richard S. Hall8df9ab12009-07-24 17:06:37 +00001213 * The returned child names are mangled ({@link Uri#mangle(String)}). The elements
Christian van Spaandonk63814412008-08-02 09:56:01 +00001214 * are in no particular order. The returned array must not contain
1215 * <code>null</code> entries.
1216 *
1217 * @param nodeUri the URI of the node
1218 * @return the list of child node names as a string array or an empty string
1219 * array if the node has no children
1220 * @throws DmtException with the following possible error codes:
1221 * <ul>
1222 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1223 * segment of it is too long, or if it has too many segments
1224 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1225 * <code>null</code> or syntactically invalid
1226 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1227 * points to a non-existing node
1228 * <li><code>PERMISSION_DENIED</code> if the session is
1229 * associated with a principal and the ACL of the node does not
1230 * allow the <code>Get</code> operation for the associated
1231 * principal
1232 * <li><code>COMMAND_NOT_ALLOWED</code> if the specified node is
1233 * not an interior node
1234 * <li><code>METADATA_MISMATCH</code> if node information cannot
1235 * be retrieved according to the meta-data (it does not have
1236 * <code>MetaNode.CMD_GET</code> access type)
1237 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1238 * accessing the data store
1239 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1240 * current session's subtree, or if some unspecified error is
1241 * encountered while attempting to complete the command
1242 * </ul>
1243 * @throws DmtIllegalStateException if the session is already closed or
1244 * invalidated
1245 * @throws SecurityException if the caller does not have the necessary
1246 * permissions to execute the underlying management operation, or,
1247 * in case of local sessions, if the caller does not have
1248 * <code>DmtPermission</code> for the node with the Get action
1249 * present
1250 */
1251 String[] getChildNodeNames(String nodeUri) throws DmtException;
1252
1253 /**
1254 * Get the meta data which describes a given node. Meta data can only be
1255 * inspected, it can not be changed.
1256 * <p>
1257 * The <code>MetaNode</code> object returned to the client is the
1258 * combination of the meta data returned by the data plugin (if any) plus
1259 * the meta data returned by the DmtAdmin. If there are differences in the
1260 * meta data elements known by the plugin and the DmtAdmin then the plugin
1261 * specific elements take precedence.
1262 * <p>
1263 * Note, that a node does not have to exist for having meta-data associated
1264 * with it. This method may provide meta-data for any node that can possibly
1265 * exist in the tree (any node defined in the specification). For nodes that
1266 * are not defined, it may throw <code>DmtException</code> with the error
1267 * code <code>NODE_NOT_FOUND</code>. To allow easier implementation of
1268 * plugins that do not provide meta-data, it is allowed to return
1269 * <code>null</code> for any node, regardless of whether it is defined or
1270 * not.
1271 *
1272 * @param nodeUri the URI of the node
1273 * @return a MetaNode which describes meta data information, can be
1274 * <code>null</code> if there is no meta data available for the
1275 * given node
1276 * @throws DmtException with the following possible error codes:
1277 * <ul>
1278 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1279 * segment of it is too long, or if it has too many segments
1280 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1281 * <code>null</code> or syntactically invalid
1282 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1283 * points to a node that is not defined in the tree (see above)
1284 * <li><code>PERMISSION_DENIED</code> if the session is
1285 * associated with a principal and the ACL of the node does not
1286 * allow the <code>Get</code> operation for the associated
1287 * principal
1288 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1289 * accessing the data store
1290 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1291 * current session's subtree, or if some unspecified error is
1292 * encountered while attempting to complete the command
1293 * </ul>
1294 * @throws DmtIllegalStateException if the session is already closed or
1295 * invalidated
1296 * @throws SecurityException if the caller does not have the necessary
1297 * permissions to execute the underlying management operation, or,
1298 * in case of local sessions, if the caller does not have
1299 * <code>DmtPermission</code> for the node with the Get action
1300 * present
1301 */
1302 MetaNode getMetaNode(String nodeUri) throws DmtException;
1303
1304 /**
1305 * Get the size of the data in a leaf node. The returned value depends on
1306 * the format of the data in the node, see the description of the
1307 * {@link DmtData#getSize()} method for the definition of node size for each
1308 * format.
1309 *
1310 * @param nodeUri the URI of the leaf node
1311 * @return the size of the data in the node
1312 * @throws DmtException with the following possible error codes:
1313 * <ul>
1314 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1315 * segment of it is too long, or if it has too many segments
1316 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1317 * <code>null</code> or syntactically invalid
1318 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1319 * points to a non-existing node
1320 * <li><code>PERMISSION_DENIED</code> if the session is
1321 * associated with a principal and the ACL of the node does not
1322 * allow the <code>Get</code> operation for the associated
1323 * principal
1324 * <li><code>COMMAND_NOT_ALLOWED</code> if the specified node is
1325 * not a leaf node
1326 * <li><code>METADATA_MISMATCH</code> if node information cannot
1327 * be retrieved according to the meta-data (it does not have
1328 * <code>MetaNode.CMD_GET</code> access type)
1329 * <li><code>FEATURE_NOT_SUPPORTED</code> if the Size property is
1330 * not supported by the DmtAdmin implementation or the underlying
1331 * plugin
1332 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1333 * accessing the data store
1334 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1335 * current session's subtree, or if some unspecified error is
1336 * encountered while attempting to complete the command
1337 * </ul>
1338 * @throws DmtIllegalStateException if the session is already closed or
1339 * invalidated
1340 * @throws SecurityException if the caller does not have the necessary
1341 * permissions to execute the underlying management operation, or,
1342 * in case of local sessions, if the caller does not have
1343 * <code>DmtPermission</code> for the node with the Get action
1344 * present
1345 * @see DmtData#getSize
1346 */
1347 int getNodeSize(String nodeUri) throws DmtException;
1348
1349 /**
1350 * Get the timestamp when the node was created or last modified.
1351 *
1352 * @param nodeUri the URI of the node
1353 * @return the timestamp of the last modification
1354 * @throws DmtException with the following possible error codes:
1355 * <ul>
1356 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1357 * segment of it is too long, or if it has too many segments
1358 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1359 * <code>null</code> or syntactically invalid
1360 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1361 * points to a non-existing node
1362 * <li><code>PERMISSION_DENIED</code> if the session is
1363 * associated with a principal and the ACL of the node does not
1364 * allow the <code>Get</code> operation for the associated
1365 * principal
1366 * <li><code>METADATA_MISMATCH</code> if node information cannot
1367 * be retrieved according to the meta-data (it does not have
1368 * <code>MetaNode.CMD_GET</code> access type)
1369 * <li><code>FEATURE_NOT_SUPPORTED</code> if the Timestamp
1370 * property is not supported by the DmtAdmin implementation or the
1371 * underlying plugin
1372 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1373 * accessing the data store
1374 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1375 * current session's subtree, or if some unspecified error is
1376 * encountered while attempting to complete the command
1377 * </ul>
1378 * @throws DmtIllegalStateException if the session is already closed or
1379 * invalidated
1380 * @throws SecurityException if the caller does not have the necessary
1381 * permissions to execute the underlying management operation, or,
1382 * in case of local sessions, if the caller does not have
1383 * <code>DmtPermission</code> for the node with the Get action
1384 * present
1385 */
1386 Date getNodeTimestamp(String nodeUri) throws DmtException;
1387
1388 /**
1389 * Get the title of a node. There might be no title property set for a node.
1390 *
1391 * @param nodeUri the URI of the node
1392 * @return the title of the node, or <code>null</code> if the node has no
1393 * title
1394 * @throws DmtException with the following possible error codes:
1395 * <ul>
1396 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1397 * segment of it is too long, or if it has too many segments
1398 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1399 * <code>null</code> or syntactically invalid
1400 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1401 * points to a non-existing node
1402 * <li><code>PERMISSION_DENIED</code> if the session is
1403 * associated with a principal and the ACL of the node does not
1404 * allow the <code>Get</code> operation for the associated
1405 * principal
1406 * <li><code>METADATA_MISMATCH</code> if node information cannot
1407 * be retrieved according to the meta-data (it does not have
1408 * <code>MetaNode.CMD_GET</code> access type)
1409 * <li><code>FEATURE_NOT_SUPPORTED</code> if the Title property
1410 * is not supported by the DmtAdmin implementation or the
1411 * underlying plugin
1412 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1413 * accessing the data store
1414 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1415 * current session's subtree, or if some unspecified error is
1416 * encountered while attempting to complete the command
1417 * </ul>
1418 * @throws DmtIllegalStateException if the session is already closed or
1419 * invalidated
1420 * @throws SecurityException if the caller does not have the necessary
1421 * permissions to execute the underlying management operation, or,
1422 * in case of local sessions, if the caller does not have
1423 * <code>DmtPermission</code> for the node with the Get action
1424 * present
1425 */
1426 String getNodeTitle(String nodeUri) throws DmtException;
1427
1428 /**
1429 * Get the type of a node. The type of leaf node is the MIME type of the
1430 * data it contains. The type of an interior node is a URI identifying a DDF
1431 * document; a <code>null</code> type means that there is no DDF document
1432 * overriding the tree structure defined by the ancestors.
1433 *
1434 * @param nodeUri the URI of the node
1435 * @return the type of the node, can be <code>null</code>
1436 * @throws DmtException with the following possible error codes:
1437 * <ul>
1438 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1439 * segment of it is too long, or if it has too many segments
1440 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1441 * <code>null</code> or syntactically invalid
1442 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1443 * points to a non-existing node
1444 * <li><code>PERMISSION_DENIED</code> if the session is
1445 * associated with a principal and the ACL of the node does not
1446 * allow the <code>Get</code> operation for the associated
1447 * principal
1448 * <li><code>METADATA_MISMATCH</code> if node information cannot
1449 * be retrieved according to the meta-data (it does not have
1450 * <code>MetaNode.CMD_GET</code> access type)
1451 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1452 * accessing the data store
1453 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1454 * current session's subtree, or if some unspecified error is
1455 * encountered while attempting to complete the command
1456 * </ul>
1457 * @throws DmtIllegalStateException if the session is already closed or
1458 * invalidated
1459 * @throws SecurityException if the caller does not have the necessary
1460 * permissions to execute the underlying management operation, or,
1461 * in case of local sessions, if the caller does not have
1462 * <code>DmtPermission</code> for the node with the Get action
1463 * present
1464 */
1465 String getNodeType(String nodeUri) throws DmtException;
1466
1467 /**
1468 * Get the data contained in a leaf or interior node. When retrieving the
1469 * value associated with an interior node, the caller must have rights to
1470 * read all nodes in the subtree under the given node.
1471 *
1472 * @param nodeUri the URI of the node to retrieve
1473 * @return the data of the node, can not be <code>null</code>
1474 * @throws DmtException with the following possible error codes:
1475 * <ul>
1476 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1477 * segment of it is too long, or if it has too many segments
1478 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1479 * <code>null</code> or syntactically invalid
1480 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1481 * points to a non-existing node
1482 * <li><code>PERMISSION_DENIED</code> if the session is
1483 * associated with a principal and the ACL of the node (and the ACLs
1484 * of all its descendants in case of interior nodes) do not allow
1485 * the <code>Get</code> operation for the associated principal
1486 * <li><code>METADATA_MISMATCH</code> if the node value cannot be
1487 * retrieved according to the meta-data (it does not have
1488 * <code>MetaNode.CMD_GET</code> access type)
1489 * <li><code>FEATURE_NOT_SUPPORTED</code> if the specified node is
1490 * an interior node and does not support Java object values
1491 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1492 * accessing the data store
1493 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1494 * current session's subtree, or if some unspecified error is
1495 * encountered while attempting to complete the command
1496 * </ul>
1497 * @throws DmtIllegalStateException if the session is already closed or
1498 * invalidated
1499 * @throws SecurityException if the caller does not have the necessary
1500 * permissions to execute the underlying management operation, or,
1501 * in case of local sessions, if the caller does not have
1502 * <code>DmtPermission</code> for the node (and all its descendants
1503 * in case of interior nodes) with the Get action present
1504 */
1505 DmtData getNodeValue(String nodeUri) throws DmtException;
1506
1507 /**
1508 * Get the version of a node. The version can not be set, it is calculated
1509 * automatically by the device. It is incremented modulo 0x10000 at every
1510 * modification of the value or any other property of the node, for both
1511 * leaf and interior nodes. When a node is created the initial value is 0.
1512 *
1513 * @param nodeUri the URI of the node
1514 * @return the version of the node
1515 * @throws DmtException with the following possible error codes:
1516 * <ul>
1517 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1518 * segment of it is too long, or if it has too many segments
1519 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1520 * <code>null</code> or syntactically invalid
1521 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1522 * points to a non-existing node
1523 * <li><code>PERMISSION_DENIED</code> if the session is
1524 * associated with a principal and the ACL of the node does not
1525 * allow the <code>Get</code> operation for the associated
1526 * principal
1527 * <li><code>METADATA_MISMATCH</code> if node information cannot
1528 * be retrieved according to the meta-data (it does not have
1529 * <code>MetaNode.CMD_GET</code> access type)
1530 * <li><code>FEATURE_NOT_SUPPORTED</code> if the Version property
1531 * is not supported by the DmtAdmin implementation or the
1532 * underlying plugin
1533 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1534 * accessing the data store
1535 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1536 * current session's subtree, or if some unspecified error is
1537 * encountered while attempting to complete the command
1538 * </ul>
1539 * @throws DmtIllegalStateException if the session is already closed or
1540 * invalidated
1541 * @throws SecurityException if the caller does not have the necessary
1542 * permissions to execute the underlying management operation, or,
1543 * in case of local sessions, if the caller does not have
1544 * <code>DmtPermission</code> for the node with the Get action
1545 * present
1546 */
1547 int getNodeVersion(String nodeUri) throws DmtException;
1548
1549 /**
1550 * Tells whether a node is a leaf or an interior node of the DMT.
1551 *
1552 * @param nodeUri the URI of the node
1553 * @return true if the given node is a leaf node
1554 * @throws DmtException with the following possible error codes:
1555 * <ul>
1556 * <li><code>URI_TOO_LONG</code> if <code>nodeUri</code> or a
1557 * segment of it is too long, or if it has too many segments
1558 * <li><code>INVALID_URI</code> if <code>nodeUri</code> is
1559 * <code>null</code> or syntactically invalid
1560 * <li><code>NODE_NOT_FOUND</code> if <code>nodeUri</code>
1561 * points to a non-existing node
1562 * <li><code>PERMISSION_DENIED</code> if the session is
1563 * associated with a principal and the ACL of the node does not
1564 * allow the <code>Get</code> operation for the associated
1565 * principal
1566 * <li><code>METADATA_MISMATCH</code> if node information cannot
1567 * be retrieved according to the meta-data (it does not have
1568 * <code>MetaNode.CMD_GET</code> access type)
1569 * <li><code>DATA_STORE_FAILURE</code> if an error occurred while
1570 * accessing the data store
1571 * <li><code>COMMAND_FAILED</code> if the URI is not within the
1572 * current session's subtree, or if some unspecified error is
1573 * encountered while attempting to complete the command
1574 * </ul>
1575 * @throws DmtIllegalStateException if the session is already closed or
1576 * invalidated
1577 * @throws SecurityException if the caller does not have the necessary
1578 * permissions to execute the underlying management operation, or,
1579 * in case of local sessions, if the caller does not have
1580 * <code>DmtPermission</code> for the node with the Get action
1581 * present
1582 */
1583 boolean isLeafNode(String nodeUri) throws DmtException;
1584
1585 /**
1586 * Check whether the specified URI corresponds to a valid node in the DMT.
1587 *
1588 * @param nodeUri the URI to check
1589 * @return true if the given node exists in the DMT
1590 * @throws DmtIllegalStateException if the session is already closed or
1591 * invalidated
1592 * @throws SecurityException if the caller does not have the necessary
1593 * permissions to execute the underlying management operation, or,
1594 * in case of local sessions, if the caller does not have
1595 * <code>DmtPermission</code> for the node with the Get action
1596 * present
1597 */
1598 boolean isNodeUri(String nodeUri);
1599}