add doc and example

examples/src/main/resources/META-INF/services/org.apache.spark.sql.SparkSessionExtensionsProvider

@@ -0,0 +1 @@
+org.apache.spark.examples.extensions.SessionExtensionsWithLoader

examples/src/main/scala/org/apache/spark/examples/extensions/AgeExample.scala

@@ -0,0 +1,31 @@
+/*
+ * 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
+ *
+ *    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 org.apache.spark.examples.extensions
+
+import org.apache.spark.sql.catalyst.expressions.{CurrentDate, Expression, RuntimeReplaceable, SubtractDates}
+
+/**
+ * How old are you in days?
+ */
+case class AgeExample(birthday: Expression, child: Expression) extends RuntimeReplaceable {
+
+  def this(birthday: Expression) = this(birthday, SubtractDates(CurrentDate(), birthday))
+  override def exprsReplaced: Seq[Expression] = Seq(birthday)
+
+  override protected def withNewChildInternal(newChild: Expression): Expression = copy(newChild)
+}

examples/src/main/scala/org/apache/spark/examples/extensions/SessionExtensionsWithLoader.scala

@@ -0,0 +1,31 @@
+/*
+ * 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
+ *
+ *    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 org.apache.spark.examples.extensions
+
+import org.apache.spark.sql.{SparkSessionExtensions, SparkSessionExtensionsProvider}
+import org.apache.spark.sql.catalyst.FunctionIdentifier
+import org.apache.spark.sql.catalyst.expressions.{Expression, ExpressionInfo}
+
+class SessionExtensionsWithLoader extends SparkSessionExtensionsProvider {
+  override def apply(v1: SparkSessionExtensions): Unit = {
+    v1.injectFunction(
+      (new FunctionIdentifier("age_two"),
+        new ExpressionInfo(classOf[AgeExample].getName,
+        "age_two"), (children: Seq[Expression]) => new AgeExample(children.head)))
+  }
+}

examples/src/main/scala/org/apache/spark/examples/extensions/SessionExtensionsWithoutLoader.scala

@@ -0,0 +1,31 @@
+/*
+ * 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
+ *
+ *    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 org.apache.spark.examples.extensions
+
+import org.apache.spark.sql.{SparkSessionExtensions, SparkSessionExtensionsProvider}
+import org.apache.spark.sql.catalyst.FunctionIdentifier
+import org.apache.spark.sql.catalyst.expressions.{Expression, ExpressionInfo}
+
+class SessionExtensionsWithoutLoader extends SparkSessionExtensionsProvider {
+  override def apply(v1: SparkSessionExtensions): Unit = {
+    v1.injectFunction(
+      (new FunctionIdentifier("age_one"),
+        new ExpressionInfo(classOf[AgeExample].getName,
+        "age_one"), (children: Seq[Expression]) => new AgeExample(children.head)))
+  }
+}

examples/src/main/scala/org/apache/spark/examples/extensions/SparkSessionExtensionsTest.scala

@@ -0,0 +1,38 @@
+/*
+ * 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
+ *
+ *    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 org.apache.spark.examples.extensions
+
+import org.apache.spark.sql.SparkSession
+
+/**
+ * [[SessionExtensionsWithLoader]] is registered in
+ * src/main/resources/META-INF/services/org.apache.spark.sql.SparkSessionExtensionsProvider
+ *
+ * [[SessionExtensionsWithoutLoader]] is registered via spark.sql.extensions
+ */
+object SparkSessionExtensionsTest {
+
+  def main(args: Array[String]): Unit = {
+    val spark = SparkSession
+      .builder()
+      .appName("SparkSessionExtensionsTest")
+      .config("spark.sql.extensions", classOf[SessionExtensionsWithoutLoader].getName)
+      .getOrCreate()
+    spark.sql("SELECT age_one('2018-11-17'), age_two('2018-11-17')").show()
+  }
+}

sql/core/src/main/scala/org/apache/spark/sql/SparkSession.scala

@@ -894,7 +894,7 @@ object SparkSession extends Logging {
      *
      * @since 2.2.0
      */
-    def withExtensions(f: SparkSessionExtensionsProvider): Builder = synchronized {
+    def withExtensions(f: SparkSessionExtensions => Unit): Builder = synchronized {
       f(extensions)
       this
     }

sql/core/src/main/scala/org/apache/spark/sql/SparkSessionExtensionsProvider.scala

@@ -19,14 +19,68 @@ package org.apache.spark.sql
 
 import org.apache.spark.annotation.{DeveloperApi, Experimental, Since, Unstable}
 
+// scalastyle:off line.size.limit
 /**
  * :: Experimental ::
+ *
  * Base trait for implementations used by [[SparkSessionExtensions]]
  *
+ *
+ * For example, now we have an external function named `Age` to register as an extension for SparkSession:
+ *
+ *
+ * {{{
+ *   package org.apache.spark.examples.extensions
+ *
+ *   import org.apache.spark.sql.catalyst.expressions.{CurrentDate, Expression, RuntimeReplaceable, SubtractDates}
+ *
+ *   case class Age(birthday: Expression, child: Expression) extends RuntimeReplaceable {
+ *
+ *     def this(birthday: Expression) = this(birthday, SubtractDates(CurrentDate(), birthday))
+ *     override def exprsReplaced: Seq[Expression] = Seq(birthday)
+ *     override protected def withNewChildInternal(newChild: Expression): Expression = copy(newChild)
+ *   }
+ * }}}
+ *
+ * We need to create your extension which inherits [[SparkSessionExtensionsProvider]]
+ * Example:
+ *
+ * {{{
+ *   package org.apache.spark.examples.extensions
+ *
+ *   import org.apache.spark.sql.{SparkSessionExtensions, SparkSessionExtensionsProvider}
+ *   import org.apache.spark.sql.catalyst.FunctionIdentifier
+ *   import org.apache.spark.sql.catalyst.expressions.{Expression, ExpressionInfo}
+ *
+ *   class MyExtensions extends SparkSessionExtensionsProvider {
+ *     override def apply(v1: SparkSessionExtensions): Unit = {
+ *       v1.injectFunction(
+ *         (new FunctionIdentifier("age"),
+ *           new ExpressionInfo(classOf[Age].getName,
+ *          "age"), (children: Seq[Expression]) => new Age(children.head)))
+ *     }
+ *   }
+ * }}}
+ *
+ * We can inject `MyExtensions` in three ways,
+ * <ul>
+ *   <li>[[SparkSession.Builder.withExtensions]]</li>
+ *   <li>Config - spark.sql.extensions</li>
+ *   <li>[[java.util.ServiceLoader]] - Add to src/main/resources/META-INF/services/org.apache.spark.sql.SparkSessionExtensionsProvider</li>
+ * </ul>
+ *
+ * @see [[SparkSessionExtensions]]
+ * @see [[SparkSession.Builder.withExtensions]]
+ * @see [[java.util.ServiceLoader]]
+ *
  * @since 3.2.0
+ *
+ * @note We make NO guarantee about the stability regarding binary compatibility and source compatibility of methods here.
+ *       It's experimental and intended for developers
  */
 @DeveloperApi
 @Experimental
 @Unstable
 @Since("3.2.0")
 trait SparkSessionExtensionsProvider extends Function1[SparkSessionExtensions, Unit]
+// scalastyle:on line.size.limit