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
019 package org.apache.hadoop.registry.client.api;
020
021 import org.apache.hadoop.classification.InterfaceAudience;
022 import org.apache.hadoop.classification.InterfaceStability;
023 import org.apache.hadoop.fs.FileAlreadyExistsException;
024 import org.apache.hadoop.fs.PathIsNotEmptyDirectoryException;
025 import org.apache.hadoop.fs.PathNotFoundException;
026 import org.apache.hadoop.service.Service;
027 import org.apache.hadoop.registry.client.exceptions.InvalidPathnameException;
028 import org.apache.hadoop.registry.client.exceptions.InvalidRecordException;
029 import org.apache.hadoop.registry.client.exceptions.NoRecordException;
030 import org.apache.hadoop.registry.client.types.RegistryPathStatus;
031 import org.apache.hadoop.registry.client.types.ServiceRecord;
032
033 import java.io.IOException;
034 import java.util.List;
035
036 /**
037 * Registry Operations
038 */
039 @InterfaceAudience.Public
040 @InterfaceStability.Evolving
041 public 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 }