001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.apache.hadoop.registry.client.api;
020
021import org.apache.hadoop.classification.InterfaceAudience;
022import org.apache.hadoop.classification.InterfaceStability;
023import org.apache.hadoop.fs.FileAlreadyExistsException;
024import org.apache.hadoop.fs.PathIsNotEmptyDirectoryException;
025import org.apache.hadoop.fs.PathNotFoundException;
026import org.apache.hadoop.service.Service;
027import org.apache.hadoop.registry.client.exceptions.InvalidPathnameException;
028import org.apache.hadoop.registry.client.exceptions.InvalidRecordException;
029import org.apache.hadoop.registry.client.exceptions.NoRecordException;
030import org.apache.hadoop.registry.client.types.RegistryPathStatus;
031import org.apache.hadoop.registry.client.types.ServiceRecord;
032
033import java.io.IOException;
034import java.util.List;
035
036/**
037 * Registry Operations
038 */
039@InterfaceAudience.Public
040@InterfaceStability.Evolving
041public interface RegistryOperations extends Service {
042
043  /**
044   * Create a path.
045   *
046   * It is not an error if the path exists already, be it empty or not.
047   *
048   * The createParents flag also requests creating the parents.
049   * As entries in the registry can hold data while still having
050   * child entries, it is not an error if any of the parent path
051   * elements have service records.
052   *
053   * @param path path to create
054   * @param createParents also create the parents.
055   * @throws PathNotFoundException parent path is not in the registry.
056   * @throws InvalidPathnameException path name is invalid.
057   * @throws IOException Any other IO Exception.
058   * @return true if the path was created, false if it existed.
059   */
060  boolean mknode(String path, boolean createParents)
061      throws PathNotFoundException,
062      InvalidPathnameException,
063      IOException;
064
065  /**
066   * Bind a path in the registry to a service record
067   * @param path path to service record
068   * @param record service record service record to create/update
069   * @param flags bind flags
070   * @throws PathNotFoundException the parent path does not exist
071   * @throws FileAlreadyExistsException path exists but create flags
072   * do not include "overwrite"
073   * @throws InvalidPathnameException path name is invalid.
074   * @throws IOException Any other IO Exception.
075   */
076  void bind(String path, ServiceRecord record, int flags)
077      throws PathNotFoundException,
078      FileAlreadyExistsException,
079      InvalidPathnameException,
080      IOException;
081
082  /**
083   * Resolve the record at a path
084   * @param path path to an entry containing a {@link ServiceRecord}
085   * @return the record
086   * @throws PathNotFoundException path is not in the registry.
087   * @throws NoRecordException if there is not a service record
088   * @throws InvalidRecordException if there was a service record but it could
089   * not be parsed.
090   * @throws IOException Any other IO Exception
091   */
092
093  ServiceRecord resolve(String path)
094      throws PathNotFoundException,
095      NoRecordException,
096      InvalidRecordException,
097      IOException;
098
099  /**
100   * Get the status of a path
101   * @param path path to query
102   * @return the status of the path
103   * @throws PathNotFoundException path is not in the registry.
104   * @throws InvalidPathnameException the path is invalid.
105   * @throws IOException Any other IO Exception
106   */
107  RegistryPathStatus stat(String path)
108      throws PathNotFoundException,
109      InvalidPathnameException,
110      IOException;
111
112  /**
113   * Probe for a path existing.
114   * This is equivalent to {@link #stat(String)} with
115   * any failure downgraded to a
116   * @param path path to query
117   * @return true if the path was found
118   * @throws IOException
119   */
120  boolean exists(String path) throws IOException;
121
122  /**
123   * List all entries under a registry path, returning the relative names
124   * of the entries.
125   * @param path path to query
126   * @return a possibly empty list of the short path names of
127   * child entries.
128   * @throws PathNotFoundException
129   * @throws InvalidPathnameException
130   * @throws IOException
131   */
132   List<String> list(String path) throws
133      PathNotFoundException,
134      InvalidPathnameException,
135      IOException;
136
137  /**
138   * Delete a path.
139   *
140   * If the operation returns without an error then the entry has been
141   * deleted.
142   * @param path path delete recursively
143   * @param recursive recursive flag
144   * @throws PathNotFoundException path is not in the registry.
145   * @throws InvalidPathnameException the path is invalid.
146   * @throws PathIsNotEmptyDirectoryException path has child entries, but
147   * recursive is false.
148   * @throws IOException Any other IO Exception
149   *
150   */
151  void delete(String path, boolean recursive)
152      throws PathNotFoundException,
153      PathIsNotEmptyDirectoryException,
154      InvalidPathnameException,
155      IOException;
156
157  /**
158   * Add a new write access entry to be added to node permissions in all
159   * future write operations of a session connected to a secure registry.
160   *
161   * This does not grant the session any more rights: if it lacked any write
162   * access, it will still be unable to manipulate the registry.
163   *
164   * In an insecure cluster, this operation has no effect.
165   * @param id ID to use
166   * @param pass password
167   * @return true if the accessor was added: that is, the registry connection
168   * uses permissions to manage access
169   * @throws IOException on any failure to build the digest
170   */
171  boolean addWriteAccessor(String id, String pass) throws IOException;
172
173  /**
174   * Clear all write accessors.
175   *
176   * At this point all standard permissions/ACLs are retained,
177   * including any set on behalf of the user
178   * Only  accessors added via {@link #addWriteAccessor(String, String)}
179   * are removed.
180   */
181  public void clearWriteAccessors();
182}