| // Copyright 2015 The Vanadium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| package io.v.v23.namespace; |
| |
| import io.v.v23.VIterable; |
| import io.v.v23.rpc.Callback; |
| import org.joda.time.Duration; |
| |
| import java.util.List; |
| import java.util.Map; |
| |
| import io.v.v23.Options; |
| import io.v.v23.context.VContext; |
| import io.v.v23.naming.GlobReply; |
| import io.v.v23.naming.MountEntry; |
| import io.v.v23.security.access.Permissions; |
| import io.v.v23.verror.VException; |
| |
| /** |
| * Translation from object names to server object addresses. It represents the interface to a |
| * client side library for the {@code MountTable} service. |
| */ |
| public interface Namespace { |
| /** |
| * A shortcut for {@link #mount(VContext, String, String, Duration, Options)} with a {@code |
| * null} options parameter. |
| */ |
| void mount(VContext context, String name, String server, Duration ttl) throws VException; |
| |
| /** |
| * Mounts the server object address under the object name, expiring after {@code ttl}. {@code |
| * ttl} of zero implies an implementation-specific high value (essentially forever). |
| * <p> |
| * A particular implementation of this interface chooses which options to support, |
| * but at the minimum it must handle the following pre-defined options: |
| * <ul> |
| * <li>{@link io.v.v23.OptionDefs#SKIP_SERVER_ENDPOINT_AUTHORIZATION}</li> |
| * </ul> |
| * |
| * @param context a client context |
| * @param name a Vanadium name, see also <a href="https://github.com/vanadium/docs/blob/master/glossary.md#object-name">the |
| * Name entry</a> in the glossary |
| * @param server an object address, see also |
| * <a href="https://github.com/vanadium/docs/blob/master/concepts/naming.md#object-names">the Object names</a> |
| * section of the Naming Concepts document |
| * @param ttl the duration for which the mount should live |
| * @param options options to pass to the implementation as described above, or {@code null} |
| * @throws VException if the server object address could not be mounted |
| */ |
| void mount(VContext context, String name, String server, Duration ttl, Options options) |
| throws VException; |
| |
| /** |
| * A shortcut for {@link #mount(VContext, String, String, Duration, Options, Callback)} with |
| * a {@code null} options parameter. |
| */ |
| void mount(VContext context, String name, String server, Duration ttl, Callback<Void> callback) |
| throws VException; |
| |
| /** |
| * Asynchronous version of {@link #mount(VContext, String, String, Duration, Options)} that |
| * takes in a callback whose {@code onSuccess} method will be called when the operation |
| * completes successfully, and whose {@code onFailure} will be called if an error is |
| * encountered. |
| */ |
| void mount(VContext context, String name, String server, Duration ttl, Options options, |
| Callback<Void> callback) throws VException; |
| |
| /** |
| * A shortcut for {@link #unmount(VContext, String, String, Options)} with a {@code null} |
| * options parameter. |
| */ |
| void unmount(VContext context, String name, String server) throws VException; |
| |
| /** |
| * Unmounts the server object address from the object name, or if {@code server} is empty, |
| * unmounts all server object addresses from the object name. |
| * <p> |
| * A particular implementation of this interface chooses which options to support, |
| * but at the minimum it must handle the following pre-defined options: |
| * <ul> |
| * <li>{@link io.v.v23.OptionDefs#SKIP_SERVER_ENDPOINT_AUTHORIZATION}</li> |
| * </ul> |
| * |
| * @param context a client context |
| * @param name a Vanadium name, see also <a href="https://github.com/vanadium/docs/blob/master/glossary.md#object-name">the |
| * Name entry</a> in the glossary |
| * @param server an object address, see also |
| * <a href="https://github.com/vanadium/docs/blob/master/concepts/naming.md#object-names">the Object names</a> |
| * section of the Naming Concepts document |
| * @param options options to pass to the implementation as described above, or {@code null} |
| * @throws VException if the server object address could not be unmounted |
| */ |
| void unmount(VContext context, String name, String server, Options options) throws VException; |
| |
| /** |
| * A shortcut for {@link #unmount(VContext, String, String, Options, Callback)} with a {@code |
| * null} options parameter. |
| */ |
| void unmount(VContext context, String name, String server, Callback<Void> callback) throws |
| VException; |
| |
| /** |
| * Asynchronous version of {@link #unmount(VContext, String, String, Options)} that takes |
| * in a callback whose {@code onSuccess} method will be called when the operation completes |
| * successfully, and whose {@code onFailure} will be called if an error is encountered. |
| */ |
| void unmount(VContext context, String name, String server, Options options, Callback<Void> |
| callback) throws VException; |
| |
| /** |
| * A shortcut for {@link #delete(VContext, String, boolean, Options)} with a {@code null} |
| * options parameter. |
| */ |
| void delete(VContext context, String name, boolean deleteSubtree) throws VException; |
| |
| /** |
| * Deletes the name from a mount table. If the name has any children in its mount table, it (and |
| * its children) will only be removed if {@code deleteSubtree} is true. |
| * <p> |
| * A particular implementation of this interface chooses which options to support, |
| * but at the minimum it must handle the following pre-defined options: |
| * <ul> |
| * <li>{@link io.v.v23.OptionDefs#SKIP_SERVER_ENDPOINT_AUTHORIZATION}</li> |
| * </ul> |
| * |
| * @param context a client context |
| * @param name the Vanadium name to delete, see also |
| * <a href="https://github.com/vanadium/docs/blob/master/glossary.md#object-name">the Name entry</a> in the |
| * glossary |
| * @param deleteSubtree whether the entire tree rooted at {@code name} should be deleted |
| * @param options options to pass to the implementation as described above, or {@code null} |
| * @throws VException if the name could not be deleted |
| */ |
| void delete(VContext context, String name, boolean deleteSubtree, Options options) |
| throws VException; |
| |
| /** |
| * A shortcut for {@link #delete(VContext, String, boolean, Options, Callback)} with a {@code |
| * null} options parameter. |
| */ |
| void delete(VContext context, String name, boolean deleteSubtree, Callback<Void> callback) |
| throws VException; |
| |
| /** |
| * Asynchronous version of {@link #delete(VContext, String, boolean, Options)} that takes |
| * in a callback whose {@code onSuccess} method will be called when the operation completes |
| * successfully, and whose {@code onFailure} will be called if an error is encountered. |
| */ |
| void delete(VContext context, String name, boolean deleteSubtree, Options options, |
| Callback<Void> callback) throws VException; |
| |
| /** |
| * A shortcut for {@link #resolve(VContext, String, Options)} with a {@code null} options |
| * parameter. |
| */ |
| MountEntry resolve(VContext context, String name) throws VException; |
| |
| /** |
| * Resolves the object name into its mounted servers. |
| * <p> |
| * A particular implementation of this interface chooses which options to support, |
| * but at the minimum it must handle the following pre-defined options: |
| * <ul> |
| * <li>{@link io.v.v23.OptionDefs#SKIP_SERVER_ENDPOINT_AUTHORIZATION}</li> |
| * </ul> |
| * |
| * @param context a client context |
| * @param name the Vanadium name to resolve, see also |
| * <a href="https://github.com/vanadium/docs/blob/master/glossary.md#object-name">the Name entry</a> in the |
| * glossary |
| * @param options options to pass to the implementation as described above, or {@code null} |
| * @return the {@link MountEntry} to which the name resolves, or {@code null} if it does not |
| * resolve |
| * @throws VException if an error occurred during name resolution |
| */ |
| MountEntry resolve(VContext context, String name, Options options) throws VException; |
| |
| /** |
| * A shortcut for {@link #resolve(VContext, String, Options, Callback)} with a {@code null} |
| * options parameter. |
| */ |
| void resolve(VContext context, String name, Callback<MountEntry> callback) throws VException; |
| |
| /** |
| * Asynchronous version of {@link #resolve(VContext, String, Options)} that takes in a |
| * callback whose {@code onSuccess} method will be called when the operation completes |
| * successfully, and whose {@code onFailure} will be called if an error is encountered. |
| */ |
| void resolve(VContext context, String name, Options options, Callback<MountEntry> callback) |
| throws VException; |
| |
| /** |
| * A shortcut for {@link #resolve(VContext, String, Options)} with a {@code null} options |
| * parameter. |
| */ |
| MountEntry resolveToMountTable(VContext context, String name) throws VException; |
| |
| /** |
| * Resolves the object name into the mounttables directly responsible for the name. |
| * <p> |
| * A particular implementation of this interface chooses which options to support, |
| * but at the minimum it must handle the following pre-defined options: |
| * <ul> |
| * <li>{@link io.v.v23.OptionDefs#SKIP_SERVER_ENDPOINT_AUTHORIZATION}</li> |
| * </ul> |
| * |
| * @param context a client context |
| * @param name the Vanadium name to resolve, see also |
| * <a href="https://github.com/vanadium/docs/blob/master/glossary.md#object-name">the Name entry</a> in the |
| * glossary |
| * @param options options to pass to the implementation as described above, or {@code null} |
| * @return the {@link MountEntry} of the mounttable server directly responsible for |
| * {@code name}, or {@code null} if {@code name} does not resolve |
| * @throws VException if an error occurred during name resolution |
| */ |
| MountEntry resolveToMountTable(VContext context, String name, Options options) |
| throws VException; |
| |
| /** |
| * A shortcut for {@link #resolve(VContext, String, Options, Callback)} with a {@code null} |
| * options parameter. |
| */ |
| void resolveToMountTable(VContext context, String name, Callback<MountEntry> callback) throws |
| VException; |
| |
| /** |
| * Asynchronous version of {@link #resolveToMountTable(VContext, String, Options)} that takes |
| * in a callback whose {@code onSuccess} method will be called when the operation completes |
| * successfully, and whose {@code onFailure} will be called if an error is encountered. |
| */ |
| void resolveToMountTable(VContext context, String name, Options options, Callback<MountEntry> |
| callback) throws VException; |
| |
| /** |
| * Flushes resolution information cached for the given name. If anything was flushed it returns |
| * {@code true}. |
| * |
| * @param context a client context |
| * @param name a Vanadium name, see also <a href="https://github.com/vanadium/docs/blob/master/glossary.md#object-name">the |
| * Name entry</a> in the glossary |
| * @return {@code true} if resolution information was for the name was flushed |
| */ |
| boolean flushCacheEntry(VContext context, String name); |
| |
| /** |
| * A shortcut for {@link #glob(VContext, String, Options)} with a {@code null} options |
| * parameter. |
| */ |
| VIterable<GlobReply> glob(VContext context, String pattern) throws VException; |
| |
| /** |
| * Returns the iterator over all names matching the provided pattern. Note that due to the |
| * inherently asynchronous nature of Vanadium's glob API, you should assume that calls to |
| * the returned iterator's {@code next} method may block. |
| * <p> |
| * You should be aware that the iterator: |
| * <p><ul> |
| * <li>can be created <strong>only</strong> once</li> |
| * <li>does not support {@link java.util.Iterator#remove remove}</li> |
| * </ul> |
| * <p> |
| * A particular implementation of this interface chooses which options to support, but at the |
| * minimum it must handle the following pre-defined options: |
| * <ul> |
| * <li>{@link io.v.v23.OptionDefs#SKIP_SERVER_ENDPOINT_AUTHORIZATION}</li> |
| * </ul> |
| * <p> |
| * {@link io.v.v23.context.CancelableVContext#cancel Canceling} the provided context will |
| * stop the glob operation and terminate the iterator early. |
| * |
| * @param context a client context |
| * @param pattern a pattern that should be matched |
| * @param options options to pass to the implementation as described above, or {@code null} |
| * @return an iterator over {@link GlobReply} objects matching the provided pattern |
| * @throws VException if an error is encountered |
| */ |
| VIterable<GlobReply> glob(VContext context, String pattern, Options options) throws VException; |
| |
| /** |
| * A shortcut for {@link #glob(VContext, String, Options, Callback)} with a {@code null} options |
| * parameter. |
| */ |
| void glob(VContext context, String pattern, Callback<VIterable<GlobReply>> callback) |
| throws VException; |
| |
| /** |
| * Asynchronous version of {@link #glob(VContext, String, Options)}. |
| * |
| * @throws VException if there was an error creating the asynchronous call. In this case, no |
| * methods on {@code callback} will be called. |
| */ |
| void glob(VContext context, String pattern, Options options, Callback<VIterable<GlobReply>> |
| callback) throws VException; |
| |
| /** |
| * Sets the roots that the local namespace is relative to. |
| * <p> |
| * All relative names passed to the other methods in this class will be interpreted as |
| * relative to these roots. The roots will be tried in the order that they are specified in |
| * {@code roots} list. Calling this method with an empty list will clear the currently |
| * configured set of roots. |
| * |
| * @param roots the roots that will be used to turn relative paths into absolute paths, or |
| * {@code null} to clear the currently configured set of roots. Each entry should |
| * be a Vanadium name, see also |
| * <a href="https://github.com/vanadium/docs/blob/master/glossary.md#object-name"> |
| * the Name entry</a> in the glossary |
| */ |
| void setRoots(List<String> roots) throws VException; |
| |
| /** |
| * A shortcut for {@link #setPermissions(VContext, String, Permissions, String, Options)} with a |
| * {@code null} options parameter. |
| */ |
| void setPermissions(VContext context, String name, Permissions permissions, String version) |
| throws VException; |
| |
| /** |
| * Sets the Permissions in a node in a mount table. If the caller tries to set a permission that |
| * removes them from {@link io.v.v23.security.access.Constants#ADMIN}, the caller's original |
| * admin blessings will be retained. |
| * <p> |
| * A particular implementation of this interface chooses which options to support, |
| * but at the minimum it must handle the following pre-defined options: |
| * <ul> |
| * <li>{@link io.v.v23.OptionDefs#SKIP_SERVER_ENDPOINT_AUTHORIZATION}</li> |
| * </ul> |
| * |
| * @param context a client context |
| * @param name the name of the node receiving the new permissions |
| * @param permissions the permissions to set on the node |
| * @param version a string containing the current permissions version number (e.g. {@code "4"}. |
| * If this value does not match the version known to the receiving server, |
| * a {@link VException} is thrown indicating that this call had no effect. If the |
| * version number is not specified, no version check is performed |
| * @param options options to pass to the implementation as described above, or {@code null} |
| * @throws VException if an error is encountered (e.g. if the caller does not have permission to |
| * change the permissions) |
| */ |
| void setPermissions(VContext context, String name, Permissions permissions, String version, |
| Options options) throws VException; |
| |
| /** |
| * A shortcut for {@link #setPermissions(VContext, String, Permissions, String, Options, |
| * Callback)} with a {@code null} options parameter. |
| */ |
| void setPermissions(VContext context, String name, Permissions permissions, String version, |
| Callback<Void> callback) throws VException; |
| |
| /** |
| * Asynchronous version of {@link #setPermissions(VContext, String, Permissions, String, |
| * Options)} that takes in a callback whose {@code onSuccess} method will be called when the |
| * operation completes successfully, and whose {@code onFailure} will be called if an error is |
| * encountered. |
| */ |
| void setPermissions(VContext context, String name, Permissions permissions, String version, |
| Options options, Callback<Void> callback) throws VException; |
| |
| /** |
| * A shortcut for {@link #getPermissions(VContext, String, Options)} with a {@code null} options |
| * parameter. |
| */ |
| Map<String, Permissions> getPermissions(VContext context, String name) throws VException; |
| |
| /** |
| * Returns the Permissions in a node in a mount table. The returned map will contain a single |
| * entry whose key is the permissions version (see {@link #setPermissions(VContext, String, |
| * Permissions, String, Options)}) and whose value is the permissions corresponding to that |
| * version. |
| * <p> |
| * A particular implementation of this interface chooses which options to support, |
| * but at the minimum it must handle the following pre-defined options: |
| * <ul> |
| * <li>{@link io.v.v23.OptionDefs#SKIP_SERVER_ENDPOINT_AUTHORIZATION}</li> |
| * </ul> |
| * |
| * @param context a client context |
| * @param name the name of the node |
| * @param options options to pass to the implementation as described above, or {@code null} |
| * @return a single-entry map from permissions version to permissions for the named object |
| * @throws VException if an error is encountered |
| */ |
| Map<String, Permissions> getPermissions(VContext context, String name, Options options) |
| throws VException; |
| |
| /** |
| * A shortcut for {@link #getPermissions(VContext, String, Options, Callback)} with a |
| * {@code null} options parameter. |
| */ |
| void getPermissions(VContext context, String name, Callback<Map<String, Permissions>> |
| callback) throws VException; |
| |
| /** |
| * Asynchronous version of {@link #getPermissions(VContext, String, Options)} that takes in a |
| * callback whose {@code onSuccess} method will be called when the operation completes |
| * successfully, and whose {@code onFailure} will be called if an error is encountered. |
| */ |
| void getPermissions(VContext context, String name, Options options, Callback<Map<String, |
| Permissions>> callback) throws VException; |
| } |
