| // Copyright (C) 2020 The Android Open Source Project |
| // |
| // Licensed 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 com.google.gerrit.plugins.codeowners.backend; |
| |
| import java.io.IOException; |
| import org.eclipse.jgit.lib.ObjectId; |
| |
| /** |
| * Parser and formatter for {@link CodeOwnerConfig}s. |
| * |
| * <p>To be implemented by {@link CodeOwnerBackend}s, as the syntax that is used to represent a |
| * {@link CodeOwnerConfig} as string depends on the {@link CodeOwnerBackend}. |
| * |
| * <p>Most {@link CodeOwnerBackend}s store the string representations of {@link CodeOwnerConfig}s in |
| * files, but other storages are also possible. |
| */ |
| public interface CodeOwnerConfigParser { |
| /** |
| * Parses a {@link CodeOwnerConfig} from a string. |
| * |
| * <p>Most code owner backends store code owner configs in files. In this case the provided string |
| * is the file content. |
| * |
| * <p><strong>Note:</strong> Parsing a code owner config by using the {@link #parse(ObjectId, |
| * CodeOwnerConfig.Key, String)} and then formatting the parsed code owner config back to a string |
| * by using {@link #formatAsString(CodeOwnerConfig)} is not guaranteed to result in the exact same |
| * code owner config file (e.g. comment lines, invalid lines and invalid emails may be dropped or |
| * emails may be reordered). |
| * |
| * @param revision the revision from which the code owner configuration was loaded |
| * @param codeOwnerConfigKey the key of the code owner config that should be parsed |
| * @param codeOwnerConfigAsString the code owner configuration as string, e.g. the content of the |
| * code owner config file |
| * @return the parsed {@link CodeOwnerConfig} |
| * @throws IOException thrown if there is an IO error during the parsing |
| * @throws CodeOwnerConfigParseException thrown if the given code owner configuration string is |
| * invalid |
| */ |
| CodeOwnerConfig parse( |
| ObjectId revision, CodeOwnerConfig.Key codeOwnerConfigKey, String codeOwnerConfigAsString) |
| throws IOException, CodeOwnerConfigParseException; |
| |
| /** |
| * Formats the given code owner config as string. |
| * |
| * <p>Most code owner backends store the string representation of the code owner config in a file. |
| * |
| * @param codeOwnerConfig the code owner config that should be formatted |
| * @return the code owner config as string |
| * @throws IOException throw is there is an IO error during the formatting |
| */ |
| String formatAsString(CodeOwnerConfig codeOwnerConfig) throws IOException; |
| } |