connector/catalog/CatalogPlugin.java

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *   http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 package org.apache.spark.sql.connector.catalog;
0019
0020 import org.apache.spark.annotation.Evolving;
0021 import org.apache.spark.sql.internal.SQLConf;
0022 import org.apache.spark.sql.util.CaseInsensitiveStringMap;
0023
0024 /**
0025  * A marker interface to provide a catalog implementation for Spark.
0026  * <p>
0027  * Implementations can provide catalog functions by implementing additional interfaces for tables,
0028  * views, and functions.
0029  * <p>
0030  * Catalog implementations must implement this marker interface to be loaded by
0031  * {@link Catalogs#load(String, SQLConf)}. The loader will instantiate catalog classes using the
0032  * required public no-arg constructor. After creating an instance, it will be configured by calling
0033  * {@link #initialize(String, CaseInsensitiveStringMap)}.
0034  * <p>
0035  * Catalog implementations are registered to a name by adding a configuration option to Spark:
0036  * {@code spark.sql.catalog.catalog-name=com.example.YourCatalogClass}. All configuration properties
0037  * in the Spark configuration that share the catalog name prefix,
0038  * {@code spark.sql.catalog.catalog-name.(key)=(value)} will be passed in the case insensitive
0039  * string map of options in initialization with the prefix removed.
0040  * {@code name}, is also passed and is the catalog's name; in this case, "catalog-name".
0041  *
0042  * @since 3.0.0
0043  */
0044 @Evolving
0045 public interface CatalogPlugin {
0046   /**
0047    * Called to initialize configuration.
0048    * <p>
0049    * This method is called once, just after the provider is instantiated.
0050    *
0051    * @param name the name used to identify and load this catalog
0052    * @param options a case-insensitive string map of configuration
0053    */
0054   void initialize(String name, CaseInsensitiveStringMap options);
0055
0056   /**
0057    * Called to get this catalog's name.
0058    * <p>
0059    * This method is only called after {@link #initialize(String, CaseInsensitiveStringMap)} is
0060    * called to pass the catalog's name.
0061    */
0062   String name();
0063
0064   /**
0065    * Return a default namespace for the catalog.
0066    * <p>
0067    * When this catalog is set as the current catalog, the namespace returned by this method will be
0068    * set as the current namespace.
0069    * <p>
0070    * The namespace returned by this method is not required to exist.
0071    *
0072    * @return a multi-part namespace
0073    */
0074   default String[] defaultNamespace() {
0075     return new String[0];
0076   }
0077 }