| // 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 com.google.common.util.concurrent.ListenableFuture; |
| |
| import org.joda.time.Duration; |
| |
| import java.util.List; |
| import java.util.Map; |
| |
| import javax.annotation.CheckReturnValue; |
| |
| import io.v.v23.InputChannel; |
| 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. |
| */ |
| @CheckReturnValue |
| ListenableFuture<Void> mount(VContext context, String name, String server, Duration ttl); |
| |
| /** |
| * 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> |
| * <p> |
| * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor} |
| * specified in {@code context} (see {@link io.v.v23.V#withExecutor}). |
| * <p> |
| * The returned future will fail with {@link java.util.concurrent.CancellationException} if |
| * {@code context} gets canceled. |
| * |
| * @param context a client context |
| * @param name a Vanadium name, see also <a href="https://vanadium.github.io/glossary.html#object-name">the |
| * Name entry</a> in the glossary |
| * @param server an object address, see also |
| * <a href="https://vanadium.github.io/concepts/naming.html#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} |
| */ |
| @CheckReturnValue |
| ListenableFuture<Void> mount(VContext context, String name, String server, Duration ttl, |
| Options options); |
| |
| /** |
| * A shortcut for {@link #unmount(VContext, String, String, Options)} with a {@code null} |
| * options parameter. |
| */ |
| @CheckReturnValue |
| ListenableFuture<Void> unmount(VContext context, String name, String server); |
| |
| /** |
| * 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> |
| * <p> |
| * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor} |
| * specified in {@code context} (see {@link io.v.v23.V#withExecutor}). |
| * <p> |
| * The returned future will fail with {@link java.util.concurrent.CancellationException} if |
| * {@code context} gets canceled. |
| * |
| * @param context a client context |
| * @param name a Vanadium name, see also <a href="https://vanadium.github.io/glossary.html#object-name">the |
| * Name entry</a> in the glossary |
| * @param server an object address, see also |
| * <a href="https://vanadium.github.io/concepts/naming.html#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} |
| */ |
| @CheckReturnValue |
| ListenableFuture<Void> unmount(VContext context, String name, String server, Options options); |
| |
| /** |
| * A shortcut for {@link #delete(VContext, String, boolean, Options)} with a {@code null} |
| * options parameter. |
| */ |
| @CheckReturnValue |
| ListenableFuture<Void> delete(VContext context, String name, boolean deleteSubtree); |
| |
| /** |
| * 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> |
| * <p> |
| * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor} |
| * specified in {@code context} (see {@link io.v.v23.V#withExecutor}). |
| * <p> |
| * The returned future will fail with {@link java.util.concurrent.CancellationException} if |
| * {@code context} gets canceled. |
| * |
| * @param context a client context |
| * @param name the Vanadium name to delete, see also |
| * <a href="https://vanadium.github.io/glossary.html#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} |
| */ |
| @CheckReturnValue |
| ListenableFuture<Void> delete(VContext context, String name, boolean deleteSubtree, |
| Options options); |
| |
| /** |
| * A shortcut for {@link #resolve(VContext, String, Options)} with a {@code null} options |
| * parameter. |
| */ |
| @CheckReturnValue |
| ListenableFuture<MountEntry> resolve(VContext context, String name); |
| |
| /** |
| * 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> |
| * <p> |
| * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor} |
| * specified in {@code context} (see {@link io.v.v23.V#withExecutor}). |
| * <p> |
| * The returned future will fail with {@link java.util.concurrent.CancellationException} if |
| * {@code context} gets canceled. |
| * |
| * @param context a client context |
| * @param name the Vanadium name to resolve, see also |
| * <a href="https://vanadium.github.io/glossary.html#object-name">the Name entry</a> in the |
| * glossary |
| * @param options options to pass to the implementation as described above, or {@code null} |
| * @return a new {@link ListenableFuture} whose result is the {@link MountEntry} to which the |
| * name resolves, or {@code null} if it does not resolve |
| */ |
| @CheckReturnValue |
| ListenableFuture<MountEntry> resolve(VContext context, String name, Options options); |
| |
| /** |
| * A shortcut for {@link #resolveToMountTable(VContext, String, Options)} with a {@code null} |
| * options parameter. |
| */ |
| @CheckReturnValue |
| ListenableFuture<MountEntry> resolveToMountTable(VContext context, String name); |
| |
| /** |
| * 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> |
| * <p> |
| * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor} |
| * specified in {@code context} (see {@link io.v.v23.V#withExecutor}). |
| * <p> |
| * The returned future will fail with {@link java.util.concurrent.CancellationException} if |
| * {@code context} gets canceled. |
| * |
| * @param context a client context |
| * @param name the Vanadium name to resolve, see also |
| * <a href="https://vanadium.github.io/glossary.html#object-name">the Name entry</a> in the |
| * glossary |
| * @param options options to pass to the implementation as described above, or {@code null} |
| * @return a new {@link ListenableFuture} whose result is the {@link MountEntry} of the |
| * mounttable server directly responsible for {@code name}, or {@code null} if |
| * {@code name} does not resolve |
| */ |
| @CheckReturnValue |
| ListenableFuture<MountEntry> resolveToMountTable(VContext context, String name, |
| Options options); |
| |
| /** |
| * Sets the new caching policy, returning the previous one. |
| * <p> |
| * This is a non-blocking method. |
| * |
| * @param doCaching if {@code true}, this namespace will cache entries; otherwise, it won't |
| */ |
| boolean setCachingPolicy(boolean doCaching); |
| |
| /** |
| * Flushes resolution information cached for the given name. If anything was flushed it returns |
| * {@code true}. |
| * <p> |
| * This is a non-blocking method. |
| * |
| * @param context a client context |
| * @param name a Vanadium name, see also |
| * <a href="https://vanadium.github.io/glossary.html#object-name">the |
| * Name entry</a> in the glossary |
| * @return {@code true} iff resolution information for the name was successfully flushed |
| */ |
| boolean flushCacheEntry(VContext context, String name); |
| |
| /** |
| * A shortcut for {@link #glob(VContext, String, Options)} with a {@code null} options |
| * parameter. |
| */ |
| InputChannel<GlobReply> glob(VContext context, String pattern); |
| |
| /** |
| * Returns a channel over all names matching the provided pattern. |
| * <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.VContext#cancel Canceling} the provided context will |
| * stop the glob operation and cause the channel to stop producing elements. Note that to avoid |
| * memory leaks, the caller should drain the channel after cancelling the context. |
| * |
| * @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 {@link InputChannel} of {@link GlobReply} objects matching the provided |
| * pattern |
| */ |
| InputChannel<GlobReply> glob(VContext context, String pattern, Options options); |
| |
| /** |
| * 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. |
| * <p> |
| * This is a non-blocking method. |
| * |
| * @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://vanadium.github.io/glossary.html#object-name"> |
| * the Name entry</a> in the glossary |
| */ |
| void setRoots(List<String> roots) throws VException; |
| |
| /** |
| * Returns the currently configured roots. |
| * <p> |
| * An empty list is returned if no roots are configured. |
| * <p> |
| * This is a non-blocking method. |
| */ |
| List<String> getRoots(); |
| |
| /** |
| * A shortcut for {@link #setPermissions(VContext, String, Permissions, String, Options)} with a |
| * {@code null} options parameter. |
| */ |
| @CheckReturnValue |
| ListenableFuture<Void> setPermissions(VContext context, String name, Permissions permissions, |
| String version); |
| |
| /** |
| * 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> |
| * <p> |
| * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor} |
| * specified in {@code context} (see {@link io.v.v23.V#withExecutor}). |
| * <p> |
| * The returned future will fail with {@link java.util.concurrent.CancellationException} if |
| * {@code context} gets canceled. |
| * |
| * @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} |
| * @return a new {@link ListenableFuture} that completes when the permissions have |
| * been set |
| * |
| */ |
| @CheckReturnValue |
| ListenableFuture<Void> setPermissions(VContext context, String name, Permissions permissions, |
| String version, Options options); |
| |
| /** |
| * A shortcut for {@link #getPermissions(VContext, String, Options)} with a {@code null} options |
| * parameter. |
| */ |
| @CheckReturnValue |
| ListenableFuture<Map<String, Permissions>> getPermissions(VContext context, String name); |
| |
| /** |
| * Returns a new {@link ListenableFuture} whose result are 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> |
| * <p> |
| * The returned future is guaranteed to be executed on an {@link java.util.concurrent.Executor} |
| * specified in {@code context} (see {@link io.v.v23.V#withExecutor}). |
| * <p> |
| * The returned future will fail with {@link java.util.concurrent.CancellationException} if |
| * {@code context} gets canceled. |
| * |
| * @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 new {@link ListenableFuture} whose result is a single-entry map from |
| * permissions version to permissions for the named object |
| */ |
| @CheckReturnValue |
| ListenableFuture<Map<String, Permissions>> getPermissions(VContext context, String name, |
| Options options); |
| } |
