util-logging: New way to construct ScribeHandler for java interoperab…

…ility

Problem

The ScribeHandler class currently does not have good interoperability with Java
while constructing the ScribeHandler object because of Scala's default
parameters to constructors/companion object apply method. Java when calling the
Scala's method needs to provide values to all those default arguments which is
not ideal especially if those default arguments are not surfaced to the client
building the ScribeHandler.

Solution

The solution is to have an easy way to create the ScribeHandler instance when it
only needs the category and formatter as the parameters. This is not meant to
have all the possible ways of creating this object as a solution (for example,
by using a Builder Pattern in the ScribeHandler class)

Result

With this change there will be an additional way to construct a ScribeHandler
instance - especially for use in Java.

JIRA Issues: CSL-6923

Differential Revision: https://phabricator.twitter.biz/D208928

CHANGELOG.rst

@@ -10,6 +10,9 @@ Unreleased
 New Features
 ~~~~~~~~~~~~
 
+* util-logging: New way to construct `ScribeHandler` for java interoperability.
+  ``PHAB_ID=D208928``
+
 * util-core: Added Reader#fromAsyncStream for consuming an `AsyncStream` as a `Reader`.
   ``PHAB_ID=D202334``
 

util-logging/src/main/scala/com/twitter/logging/ScribeHandler.scala

@@ -52,10 +52,14 @@ object ScribeHandler {
 
   /**
    * Generates a HandlerFactory that returns a ScribeHandler.
-   * NOTE: ScribeHandler is usually used to write structured binary data.
+   *
+   * @note ScribeHandler is usually used to write structured binary data.
    * When used in this way, wrapping this in other handlers, such as ThrottledHandler,
    * which emit plain-text messages into the log, will corrupt the resulting data.
    *
+   * @note Java users of this library can use one of the methods in [[ScribeHandlers]],
+   * so they need not provide all the default arguments.
+   *
    * @param bufferTime
    * send a scribe message no more frequently than this:
    *
@@ -73,7 +77,7 @@ object ScribeHandler {
     formatter: Formatter = new Formatter(),
     level: Option[Level] = None,
     statsReceiver: StatsReceiver = NullStatsReceiver
-  ) =
+  ): () => ScribeHandler =
     () =>
       new ScribeHandler(
         hostname,
@@ -111,7 +115,6 @@ object ScribeHandler {
       level,
       NullStatsReceiver
     )
-
 }
 
 /**

util-logging/src/main/scala/com/twitter/logging/ScribeHandlers.scala

@@ -0,0 +1,28 @@
+package com.twitter.logging
+
+import com.twitter.finagle.stats.NullStatsReceiver
+import com.twitter.logging.ScribeHandler._
+
+object ScribeHandlers {
+  /**
+   * For Java compatibility. Calls [[ScribeHandler.apply()]] method with
+   * the provided arguments, so Java users don't need to provide the
+   * other default arguments in the call.
+   */
+  def apply(
+    category: String,
+    formatter: Formatter
+  ): () => ScribeHandler =
+    ScribeHandler.apply(
+      hostname = DefaultHostname,
+      port = DefaultPort,
+      category = category,
+      bufferTime = DefaultBufferTime,
+      connectBackoff = DefaultConnectBackoff,
+      maxMessagesPerTransaction = DefaultMaxMessagesPerTransaction,
+      maxMessagesToBuffer = DefaultMaxMessagesToBuffer,
+      formatter = formatter,
+      level = None,
+      statsReceiver = NullStatsReceiver
+    )
+}

util-logging/src/test/java/com/twitter/logging/ScribeHandlersCompilationTest.java

@@ -0,0 +1,14 @@
+package com.twitter.logging;
+
+import scala.Function0;
+
+/**
+ * Basic compilation test for calling {{{@link ScribeHandlers}}}
+ * methods from java
+ */
+public class ScribeHandlersCompilationTest {
+  public void testScribeHandlers() {
+     Function0<ScribeHandler> scribeHandlerFunc =
+         ScribeHandlers.apply("category", BareFormatter$.MODULE$);
+  }
+}