org.apache.avro.FormattedSchemaParser Maven / Gradle / Ivy

Go to download
/*
 * 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
 *
 *     https://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.avro;

import java.io.IOException;
import java.net.URI;

/**
 * Schema parser for a specific schema format.
 *
 * 
 * The {@link SchemaParser} class uses this interface, supporting text based
 * schema sources.
 * 
 *
 * 
 * Implementations are located using a {@link java.util.ServiceLoader} and must
 * therefore be threadsafe. See the {@code ServiceLoader} class for details on
 * loading your implementation.
 * 
 *
 * @see java.util.ServiceLoader
 */
public interface FormattedSchemaParser {
  /**
   * 
   * Parse schema definitions from a text based source.
   * 
   *
   * Notes for implementers:
   *
   * 
   * Schema definitions are expected not to be in the format the parser
   * expects. So when the input clearly doesn't make sense (e.g., reading "/**"
   * when expecting JSON), it is a good idea not to do anything (especially
   * calling methods on the @code ParseContext}).
   * The parameter {@code parseContext} is not thread-safe.
   * All named schema definitions that are parsed should be added to the
   * provided {@link ParseContext}.
   * Optionally, you may return a "main" schema. Some schema definitions have
   * one, for example the schema defined by the root of the JSON document in a
   * standard schema
   * definition. If unsure, return {@code null}.
   * If parsing fails, throw a {@link SchemaParseException}. This will let the
   * parsing process recover and continue.
   * Throwing anything other than a {@code SchemaParseException} will abort
   * the parsing process, so reserve that for rethrowing exceptions.
   * 
   *
   * @param parseContext    the current parse context: all named schemata that are
   *                        parsed should be added here, otherwise resolving
   *                        schemata can fail; contains all previously known types
   * @param baseUri         the base location of the schema, or {@code null} if
   *                        not known
   * @param formattedSchema the text of the schema definition(s) to parse
   * @return the main schema, if any
   * @throws IOException          when the schema cannot be read
   * @throws SchemaParseException when the schema cannot be parsed
   */
  Schema parse(ParseContext parseContext, URI baseUri, CharSequence formattedSchema)
      throws IOException, SchemaParseException;
}