<commit_before>/*
 * $Header$
 *
 * Copyright (c) OSGi Alliance (2004, 2005). All Rights Reserved.
 * 
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v1.0 which accompanies this 
 * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
 */
package org.osgi.service.dmt;

/**
 * An interface providing methods to open sessions and send alerts. The 
 * implementation of <code>DmtAdmin</code> should register itself in the OSGi 
 * service registry as a service. <code>DmtAdmin</code> is the entry point for 
 * applications to use the DMT API. The <code>getSession</code> methods are used
 * to open a session on a specified subtree of the DMT. A typical way of usage:
 * <pre>
 *  serviceRef = context.getServiceReference(DmtAdmin.class.getName());
 *  DmtAdmin factory = (DmtAdmin) context.getService(serviceRef);
 *  DmtSession session = factory.getSession(&quot;./OSGi/Configuration&quot;);
 *  session.createInteriorNode(&quot;./OSGi/Configuration/my.table&quot;);
 * </pre>
 * <p>
 * The methods for opening a session take a node URI (the session root) as 
 * 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 '\').  Any string can be converted to a valid URI
 * segment using the {@link #mangle(String)} method.
 */
public interface DmtAdmin {
    /**
     * Opens a <code>DmtSession</code> for local usage on a given subtree of
     * the DMT with non transactional write lock. This call is equivalent to the
     * following:
     * <code>getSession(null, subtreeUri, DmtSession.LOCK_TYPE_EXCLUSIVE)</code>
     * <p>
     * To access the whole tree in this session, use the &quot;.&quot; string or
     * <code>null</code> as subtree URI.
     * 
     * @param subtreeUri the subtree on which DMT manipulations can be performed
     *        within the returned session
     * @return a <code>DmtSession</code> object for the requested subtree
     * @throws DmtException with the following possible error codes:
     *         <ul>
     *         <li><code>URI_TOO_LONG</code> if <code>subtreeUri</code> or a
     *         segment of it is too long, or if it has too many segments
     *         <li><code>INVALID_URI</code> if <code>subtreeUri</code> is
     *         <code>null</code> or syntactically invalid
     *         <li><code>NODE_NOT_FOUND</code> if <code>subtreeUri</code>
     *         specifies a non-existing node
     *         <li><code>TIMEOUT</code> if the operation timed out because of
     *         another ongoing session
     *         <li><code>COMMAND_FAILED</code> for unspecified errors
     *         encountered while attempting to complete the command
     *         </ul>
     */
    DmtSession getSession(String subtreeUri) throws DmtException;

    /**
     * Opens a <code>DmtSession</code> for local usage on a specific DMT
     * subtree with a given locking mode. This call is equivalent to the
     * following: <code>getSession(null, subtreeUri, lockMode)</code>
     * <p>
     * To access the whole tree in this session, use the &quot;.&quot; string or
     * <code>null</code> as subtree URI.
     * 
     * @param subtreeUri the subtree on which DMT manipulations can be performed
     *        within the returned session
     * @param lockMode one of the locking modes specified in
     *        <code>DmtSession</code>
     * @return a <code>DmtSession</code> object for the requested subtree
     * @throws DmtException with the following possible error codes:
     *         <ul>
     *         <li><code>URI_TOO_LONG</code> if <code>subtreeUri</code> or a
     *         segment of it is too long, or if it has too many segments
     *         <li><code>INVALID_URI</code> if <code>subtreeUri</code> is
     *         <code>null</code> or syntactically invalid
     *         <li><code>NODE_NOT_FOUND</code> if <code>subtreeUri</code>
     *         specifies a non-existing node
     *         <li><code>FEATURE_NOT_SUPPORTED</code> if atomic sessions are
     *         not supported and <code>lockMode</code> requests an atomic 
     *         session
     *         <li><code>TIMEOUT</code> if the operation timed out because of
     *         another ongoing session
     *         <li><code>COMMAND_FAILED</code> if <code>lockMode</code> is
     *         unknown, or some unspecified error is encountered while 
     *         attempting to complete the command
     *         </ul>
     */
    DmtSession getSession(String subtreeUri, int lockMode)
        throws DmtException;

    /**
     * Opens a <code>DmtSession</code> on a specific DMT subtree using a
     * specific locking mode on behalf of a remote principal. If local
     * management applications are using this method then they should provide
     * <code>null</code> as the first parameter. Alternatively they can use
     * other forms of this method without providing a principal string. This
     * method is guarded by <code>DmtPrincipalPermission</code> in case of 
     * remote sessions.
     * <p>
     * To access the whole tree in this session, use the &quot;.&quot; string or
     * <code>null</code> as subtree URI.
     * 
     * @param principal the identifier of the remote server on whose behalf the
     *        data manipulation is performed, or <code>null</code> for local
     *        sessions
     * @param subtreeUri the subtree on which DMT manipulations can be performed
     *        within the returned session
     * @param lockMode one of the locking modes specified in
     *        <code>DmtSession</code>
     * @return a <code>DmtSession</code> object for the requested subtree
     * @throws DmtException with the following possible error codes:
     *         <ul>
     *         <li><code>URI_TOO_LONG</code> if <code>subtreeUri</code> or a
     *         segment of it is too long, or if it has too many segments
     *         <li><code>INVALID_URI</code> if <code>subtreeUri</code> is
     *         <code>null</code> or syntactically invalid<commit_msg>Javadoc bugfix based on TCK report: passing null URI should not result in INVALID_URI error<commit_after>/*
 * $Header$
 *
 * Copyright (c) OSGi Alliance (2004, 2005). All Rights Reserved.
 * 
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v1.0 which accompanies this 
 * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html.
 */
package org.osgi.service.dmt;

/**
 * An interface providing methods to open sessions and send alerts. The 
 * implementation of <code>DmtAdmin</code> should register itself in the OSGi 
 * service registry as a service. <code>DmtAdmin</code> is the entry point for 
 * applications to use the DMT API. The <code>getSession</code> methods are used
 * to open a session on a specified subtree of the DMT. A typical way of usage:
 * <pre>
 *  serviceRef = context.getServiceReference(DmtAdmin.class.getName());
 *  DmtAdmin factory = (DmtAdmin) context.getService(serviceRef);
 *  DmtSession session = factory.getSession(&quot;./OSGi/Configuration&quot;);
 *  session.createInteriorNode(&quot;./OSGi/Configuration/my.table&quot;);
 * </pre>
 * <p>
 * The methods for opening a session take a node URI (the session root) as 
 * 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 '\').  Any string can be converted to a valid URI
 * segment using the {@link #mangle(String)} method.
 */
public interface DmtAdmin {
    /**
     * Opens a <code>DmtSession</code> for local usage on a given subtree of
     * the DMT with non transactional write lock. This call is equivalent to the
     * following:
     * <code>getSession(null, subtreeUri, DmtSession.LOCK_TYPE_EXCLUSIVE)</code>
     * <p>
     * To access the whole tree in this session, use the &quot;.&quot; string or
     * <code>null</code> as subtree URI.
     * 
     * @param subtreeUri the subtree on which DMT manipulations can be performed
     *        within the returned session
     * @return a <code>DmtSession</code> object for the requested subtree
     * @throws DmtException with the following possible error codes:
     *         <ul>
     *         <li><code>URI_TOO_LONG</code> if <code>subtreeUri</code> or a
     *         segment of it is too long, or if it has too many segments
     *         <li><code>INVALID_URI</code> if <code>subtreeUri</code> is
     *         syntactically invalid
     *         <li><code>NODE_NOT_FOUND</code> if <code>subtreeUri</code>
     *         specifies a non-existing node
     *         <li><code>TIMEOUT</code> if the operation timed out because of
     *         another ongoing session
     *         <li><code>COMMAND_FAILED</code> for unspecified errors
     *         encountered while attempting to complete the command
     *         </ul>
     */
    DmtSession getSession(String subtreeUri) throws DmtException;

    /**
     * Opens a <code>DmtSession</code> for local usage on a specific DMT
     * subtree with a given locking mode. This call is equivalent to the
     * following: <code>getSession(null, subtreeUri, lockMode)</code>
     * <p>
     * To access the whole tree in this session, use the &quot;.&quot; string or
     * <code>null</code> as subtree URI.
     * 
     * @param subtreeUri the subtree on which DMT manipulations can be performed
     *        within the returned session
     * @param lockMode one of the locking modes specified in
     *        <code>DmtSession</code>
     * @return a <code>DmtSession</code> object for the requested subtree
     * @throws DmtException with the following possible error codes:
     *         <ul>
     *         <li><code>URI_TOO_LONG</code> if <code>subtreeUri</code> or a
     *         segment of it is too long, or if it has too many segments
     *         <li><code>INVALID_URI</code> if <code>subtreeUri</code> is
     *         syntactically invalid
     *         <li><code>NODE_NOT_FOUND</code> if <code>subtreeUri</code>
     *         specifies a non-existing node
     *         <li><code>FEATURE_NOT_SUPPORTED</code> if atomic sessions are
     *         not supported and <code>lockMode</code> requests an atomic 
     *         session
     *         <li><code>TIMEOUT</code> if the operation timed out because of
     *         another ongoing session
     *         <li><code>COMMAND_FAILED</code> if <code>lockMode</code> is
     *         unknown, or some unspecified error is encountered while 
     *         attempting to complete the command
     *         </ul>
     */
    DmtSession getSession(String subtreeUri, int lockMode)
        throws DmtException;

    /**
     * Opens a <code>DmtSession</code> on a specific DMT subtree using a
     * specific locking mode on behalf of a remote principal. If local
     * management applications are using this method then they should provide
     * <code>null</code> as the first parameter. Alternatively they can use
     * other forms of this method without providing a principal string. This
     * method is guarded by <code>DmtPrincipalPermission</code> in case of 
     * remote sessions.
     * <p>
     * To access the whole tree in this session, use the &quot;.&quot; string or
     * <code>null</code> as subtree URI.
     * 
     * @param principal the identifier of the remote server on whose behalf the
     *        data manipulation is performed, or <code>null</code> for local
     *        sessions
     * @param subtreeUri the subtree on which DMT manipulations can be performed
     *        within the returned session
     * @param lockMode one of the locking modes specified in
     *        <code>DmtSession</code>
     * @return a <code>DmtSession</code> object for the requested subtree
     * @throws DmtException with the following possible error codes:
     *         <ul>
     *         <li><code>URI_TOO_LONG</code> if <code>subtreeUri</code> or a
     *         segment of it is too long, or if it has too many segments
     *         <li><code>INVALID_URI</code> if <code>subtreeUri</code> is
     *         syntactically invalid
{'fraction_non_alphanumeric': 0.09054766734279919, 'fraction_numerical': 0.001947261663286004, 'mean_word_length': 2.705953096812989, 'pattern_counts': {'":': 0, '<': 225, '<?xml version=': 0, '>': 225, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2276797', 'n_tokens_mistral': 3492, 'n_tokens_neox': 3415, 'n_words': 1299}