| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.distributedlog.api.namespace; |
| |
| import java.io.IOException; |
| import java.util.Iterator; |
| import java.util.Optional; |
| import org.apache.bookkeeper.common.annotation.InterfaceAudience.Public; |
| import org.apache.bookkeeper.common.annotation.InterfaceStability.Evolving; |
| import org.apache.bookkeeper.stats.StatsLogger; |
| import org.apache.distributedlog.DistributedLogConfiguration; |
| import org.apache.distributedlog.acl.AccessControlManager; |
| import org.apache.distributedlog.api.DistributedLogManager; |
| import org.apache.distributedlog.callback.NamespaceListener; |
| import org.apache.distributedlog.config.DynamicDistributedLogConfiguration; |
| import org.apache.distributedlog.exceptions.InvalidStreamNameException; |
| import org.apache.distributedlog.exceptions.LogNotFoundException; |
| import org.apache.distributedlog.namespace.NamespaceDriver; |
| |
| /** |
| * A namespace is the basic unit for managing a set of distributedlogs. |
| * |
| * <h4>Namespace Interface</h4> |
| * |
| * <P> |
| * The <code>Namespace</code> interface is implemented by different backend providers. |
| * There are several components are required for an implementation: |
| * <OL> |
| * <LI>Log Management -- manage logs in a given namespace. e.g. create/open/delete log, list of logs, |
| * watch the changes of logs. |
| * <LI>Access Control -- manage the access controls for logs in the namespace. |
| * </OL> |
| * </P> |
| * |
| * <h4>Namespace Location</h4> |
| * |
| * <p>At the highest level, a <code>Namespace</code> is located by a <code>URI</code>. The location |
| * URI is in string form has the syntax</p> |
| * |
| * <blockquote> |
| * distributedlog[<tt><b>-</b></tt><i>provider</i>]<tt><b>:</b></tt><i>provider-specific-path</i> |
| * </blockquote> |
| * |
| * <p>where square brackets [...] delineate optional components and the characters |
| * <tt><b>-</b></tt> and <tt><b>:</b></tt> |
| * stand for themselves.</p> |
| * |
| * <p>The <code>provider</code> part in the URI indicates what is the backend used for this namespace. For example: |
| * <i>distributedlog-bk</i> URI is storing logs in bookkeeper, while <i>distributedlog-mem</i> URI is storing logs in |
| * memory. The <code>provider</code> part is optional. It would use bookkeeper backend if the <i>provider</i> part |
| * is omitted.</p> |
| * |
| * @see DistributedLogManager |
| * @since 0.3.32 |
| */ |
| @Public |
| @Evolving |
| public interface Namespace { |
| |
| /** |
| * Get the namespace driver used by this namespace. |
| * |
| * @return namespace driver |
| */ |
| NamespaceDriver getNamespaceDriver(); |
| |
| // |
| // Method to operate logs |
| // |
| |
| /** |
| * Create a log named <i>logName</i>. |
| * |
| * @param logName |
| * name of the log |
| * @throws InvalidStreamNameException if log name is invalid. |
| * @throws IOException when encountered issues with backend. |
| */ |
| void createLog(String logName) |
| throws InvalidStreamNameException, IOException; |
| |
| /** |
| * Delete a log named <i>logName</i>. |
| * |
| * @param logName |
| * name of the log |
| * @throws InvalidStreamNameException if log name is invalid |
| * @throws LogNotFoundException if log doesn't exist |
| * @throws IOException when encountered issues with backend |
| */ |
| void deleteLog(String logName) |
| throws InvalidStreamNameException, LogNotFoundException, IOException; |
| |
| /** |
| * Open a log named <i>logName</i>. |
| * A distributedlog manager is returned to access log <i>logName</i>. |
| * |
| * @param logName |
| * name of the log |
| * @return distributedlog manager instance. |
| * @throws InvalidStreamNameException if log name is invalid. |
| * @throws IOException when encountered issues with backend. |
| */ |
| DistributedLogManager openLog(String logName) |
| throws InvalidStreamNameException, IOException; |
| |
| /** |
| * Open a log named <i>logName</i> with specific log configurations. |
| * |
| * <p>This method allows the caller to override global configuration settings by |
| * supplying log configuration overrides. Log config overrides come in two flavors, |
| * static and dynamic. Static config never changes in the lifecyle of <code>DistributedLogManager</code>, |
| * dynamic config changes by reloading periodically and safe to access from any context.</p> |
| * |
| * @param logName |
| * name of the log |
| * @param logConf |
| * static log configuration |
| * @param dynamicLogConf |
| * dynamic log configuration |
| * @return distributedlog manager instance. |
| * @throws InvalidStreamNameException if log name is invalid. |
| * @throws IOException when encountered issues with backend. |
| */ |
| DistributedLogManager openLog(String logName, |
| Optional<DistributedLogConfiguration> logConf, |
| Optional<DynamicDistributedLogConfiguration> dynamicLogConf, |
| Optional<StatsLogger> perStreamStatsLogger) |
| throws InvalidStreamNameException, IOException; |
| |
| /** |
| * Check whether the log <i>logName</i> exist. |
| * |
| * @param logName |
| * name of the log |
| * @return <code>true</code> if the log exists, otherwise <code>false</code>. |
| * @throws IOException when encountered exceptions on checking |
| */ |
| boolean logExists(String logName) |
| throws IOException; |
| |
| /** |
| * Retrieve the logs under the namespace. |
| * |
| * @return iterator of the logs under the namespace. |
| * @throws IOException when encountered issues with backend. |
| */ |
| Iterator<String> getLogs() |
| throws IOException; |
| |
| // |
| // Methods for namespace |
| // |
| |
| /** |
| * Register namespace listener on stream updates under the namespace. |
| * |
| * @param listener |
| * listener to receive stream updates under the namespace |
| */ |
| void registerNamespaceListener(NamespaceListener listener); |
| |
| /** |
| * Create an access control manager to manage/check acl for logs. |
| * |
| * @return access control manager for logs under the namespace. |
| * @throws IOException |
| */ |
| AccessControlManager createAccessControlManager() |
| throws IOException; |
| |
| /** |
| * Close the namespace. |
| */ |
| void close(); |
| |
| } |