site publish by finaglehelper

_sources/user-guide/getting-started/comparison.rst.txt

@@ -0,0 +1,51 @@
+.. _comparison:
+
+TwitterServer v. App Comparison
+===============================
+
+General Guideline
+-----------------
+Choose an injectable ``c.t.inject.app.App`` for short-lived processes. The App runs for a few minutes
+or a few hours. Apps can make requests over the network to clients. However, they do not expose and
+bind to a port to serve external traffic. The health of the App does not need to be monitored closely.
+To collect metrics from an App, users must explicitly write metrics to a file storage
+or push them before the app shuts down. For example, cron CI jobs, command line utilities.
+
+TwitterServer is `an extension of App <./framework.html>`__, so it has every App feature and
+some additional features. If you need to serve external traffic, use a TwitterServer. The
+TwitterServer `HTTP admin page <https://twitter.github.io/twitter-server/Admin.html>`__ provides
+utilities to monitor the server health, debug performance issues, and exposes an HTTP endpoint 
+for metrics collection. Create a ``c.t.server.TwitterServer`` for long-lived servers. 
+
+.. list-table::
+   :widths: 30 35 35
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Feature
+     - TwitterServer
+     - App
+   * - Purpose
+     - Servers that continuously serve requests
+     - Jobs that start up, do some work, and then shut down. Command line utilities.
+   * - Duration
+     - Long-lived
+     - Short-lived
+   * - Exporting Metrics
+     - Exposes metrics from TwitterServer HTTP admin endpoint. An external polling system can collect the metrics at regular time intervals (e.g. every minute).
+     - Users need to set up exporting metrics before the App shuts down. Metrics can be pushed to a remote storage system or written to disk.
+   * - Bind and expose port to serve external traffic
+     - Yes ✅
+     - No ❌
+   * - `Warmup Lifecycle Phase Before Starting to Serving Traffic <lifecycle.html#c-t-server-twitterserver-lifecycle>`__
+     - Yes ✅ `prebindWarmup` and `warmupComplete`
+     - No ❌
+   * - Flags
+     - Yes ✅
+     - Yes ✅
+   * - Modules
+     - Yes ✅
+     - Yes ✅
+   * - TwitterServer HTTP Admin page (metrics, dynamic log level change page)
+     - Yes ✅
+     - No ❌

_sources/user-guide/getting-started/lifecycle.rst.txt

@@ -34,6 +34,11 @@ method or in the application or server callbacks.
    `super.lifecycleMethod()` in your override to ensure that framework lifecycle events happen
    accordingly.
 
+Choosing between TwitterServer and App
+--------------------------------------
+See the `TwitterServer v. App comparison chart <./comparison.html>`__ to decide
+between an App or TwitterServer.
+
 See the `Creating an injectable App <../app/index.html>`__ and
 `Creating an injectable TwitterServer <../twitter-server/index.html>`__ sections for more information.
 

_sources/user-guide/http/server.rst.txt

@@ -59,6 +59,10 @@ Or in Java, extend the `c.t.finatra.http.AbstractHttpServer <https://github.com/
       }
     }
 
+.. tip::
+
+  See the server `naming conventions <#naming-convention>`__ which is especially important for Java users.
+
 A more complete example includes adding Modules, a Controller, and Filters. In Scala:
 
 .. code:: scala
@@ -127,6 +131,11 @@ in Java:
       }
     }
 
+
+.. tip::
+
+  Take a look at the server `naming conventions <#naming-convention>`__ which is especially important for Java users.
+
 Adding filters in Java can happen in multiple ways which is somewhat dependent on your tolerance to
 type erasure if you need to apply Filters that have `parameterized types <https://github.com/google/guice/wiki/FrequentlyAskedQuestions#how-to-inject-class-with-generic-type>`__.
 
@@ -159,7 +168,7 @@ Additionally, a server can define `modules <../getting-started/modules.html>`__
 Naming Convention
 -----------------
 
-The Finatra convention is to create a Scala `object <https://twitter.github.io/scala_school/basics2.html#object>`__ 
+The Finatra convention for defining a server is to create a Scala `object <https://twitter.github.io/scala_school/basics2.html#object>`__ 
 with a name ending in "Main" that extends your server class. The server *class* can be used in 
 testing as this allows your server to be instantiated multiple times in tests without worrying about 
 static state persisting across test runs in the same JVM.
@@ -175,8 +184,7 @@ for running the server in all other cases.
 Java Naming Convention
 ~~~~~~~~~~~~~~~~~~~~~~
 
-In Java you would create a separate "main" class which defines a static `main()` method and accepts args
-for flag parsing:
+Similarly, in Java the best practice is to create a separate "main" class which defines a Java `main() <https://docs.oracle.com/javase/tutorial/getStarted/application/index.html#MAIN>`__ method that accepts the Java `command-line arguments <https://docs.oracle.com/javase/tutorial/essential/environment/cmdLineArgs.html#:~:text=A%20Java%20application%20can%20accept,when%20the%20application%20is%20launched.&text=When%20an%20application%20is%20launched,an%20array%20of%20String%20s.>`__ for flag parsing:
 
 .. code:: java
 
@@ -189,7 +197,7 @@ for flag parsing:
         }
     }
 
-This would be the class used as the `application entry point <https://docs.oracle.com/javase/tutorial/deployment/jar/appman.html>`__
+The `ExampleServerMain` would be the class used as the `application entry point <https://docs.oracle.com/javase/tutorial/deployment/jar/appman.html>`__
 for running the server.
 
 Creating an HTTPS Server

_sources/user-guide/http/warmup.rst.txt

@@ -70,8 +70,8 @@ following handler:
 
 .. code:: scala
 
+    import com.twitter.finatra.http.request.RequestBuilder._
     import com.twitter.finatra.http.routing.HttpWarmup
-    import com.twitter.finatra.httpclient.RequestBuilder._
     import com.twitter.inject.utils.Handler
     import scala.util.control.NonFatal
     import javax.inject.Inject

_sources/user-guide/index.rst.txt

@@ -10,6 +10,7 @@ Getting Started
 - :doc:`getting-started/dependency_injection`
 - :doc:`getting-started/framework`
 - :doc:`getting-started/twitter_server`
+- :doc:`getting-started/comparison`
 - :doc:`getting-started/lifecycle`
 - :doc:`getting-started/modules`
 - :doc:`getting-started/binding_annotations`
@@ -34,6 +35,7 @@ Injectable TwitterServer
 ------------------------
 
 - :doc:`twitter-server/index`
+- :doc:`twitter-server/update`
 
 StatsReceiver
 -------------
@@ -91,13 +93,6 @@ Clients
 
 - :doc:`thrift/clients`
 
-Kafka Streams
--------------
-
-- :doc:`kafka-streams/index`
-- :doc:`kafka-streams/examples`
-- :doc:`kafka-streams/testing`
-
 Testing
 -------
 

_sources/user-guide/json/index.rst.txt

@@ -135,7 +135,7 @@ TwitterUtil `ScalaObjectMapper`
 -------------------------------
 
 The TwitterUtil |ScalaObjectMapper|_ is a thin wrapper around a configured |jackson-module-scala|_
-`com.fasterxml.jackson.module.scala.ScalaObjectMapper <https://github.com/FasterXML/jackson-module-scala/blob/master/src/main/scala-2.+/com/fasterxml/jackson/module/scala/ScalaObjectMapper.scala>`_.
+`com.fasterxml.jackson.module.scala.ScalaObjectMapper <https://github.com/FasterXML/jackson-module-scala/blob/master/src/main/scala-2.%2B/tools/jackson/module/scala/ScalaObjectMapper.scala>`_.
 In Finatra, the recommended way to construct a |ScalaObjectMapper|_ is via the Finatra |ScalaObjectMapperModule|_.
 
 c.t.f.jackson.modules.ScalaObjectMapperModule
@@ -229,27 +229,27 @@ Adding a Custom Serializer or Deserializer
 To register a custom serializer or deserializer, configure any custom serializer or deserializer
 via the methods provided by the |ScalaObjectMapperModule|_.
 
-- Create a new Jackson `com.fasterxml.jackson.databind.Module <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/Module.java>`_ implementation.
+- Create a new Jackson `com.fasterxml.jackson.databind.JacksonModule <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/JacksonModule.java>`_ implementation.
 
   .. tip::
 
-    To implement a new Jackson `Module <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/Module.java>`_ for adding a basic custom serializer or deserializer, you can
-    use the `com.fasterxml.jackson.databind.module.SimpleModule <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/module/SimpleModule.java>`_.
+    To implement a new Jackson `Module <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/JacksonModule.java>`_ for adding a basic custom serializer or deserializer, you can
+    use the `com.fasterxml.jackson.databind.module.SimpleModule <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/module/SimpleModule.java>`_.
 
     Note, that if you want to register a `JsonSerializer` or `JsonDeserializer` over a parameterized
     type, such as a `Collection[T]` or `Map[T, U]`, that you should instead implement
-    `com.fasterxml.jackson.databind.deser.Deserializers <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/deser/Deserializers.java>`_
-    or `com.fasterxml.jackson.databind.ser.Serializers <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/ser/Serializers.java>`_
+    `com.fasterxml.jackson.databind.deser.Deserializers <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/deser/Deserializers.java>`_
+    or `com.fasterxml.jackson.databind.ser.Serializers <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/ser/Serializers.java>`_
     which provide callbacks to match the full signatures of the class to deserialize into via a
     Jackson `JavaType`.
 
     Also note that with this usage it is generally recommended to add your `Serializers` or
-    `Deserializers` implementation via a |jackson-module-scala|_ `JacksonModule <https://github.com/FasterXML/jackson-module-scala/blob/master/src/main/scala/com/fasterxml/jackson/module/scala/JacksonModule.scala>`_.
-    (which is an extension of `com.fasterxml.jackson.databind.Module <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/Module.java>`_
+    `Deserializers` implementation via a |jackson-module-scala|_ `JacksonModule <https://github.com/FasterXML/jackson-module-scala/blob/master/src/main/scala/tools/jackson/module/scala/JacksonModule.scala>`_.
+    (which is an extension of `com.fasterxml.jackson.databind.JacksonModule <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/JacksonModule.java>`_
     and can thus be used in place). See example below.
 
 - Add your serializer or deserializer using the `SimpleModule#addSerializer` or `SimpleModule#addDeserializer` methods in your module.
-- In your custom |ScalaObjectMapperModule|_ extension, add the Jackson `Module <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/Module.java>`_ implementation to list of additional Jackson modules by overriding and implementing the `ScalaObjectMapperModule#additionalJacksonModules`.
+- In your custom |ScalaObjectMapperModule|_ extension, add the `JacksonModule <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/JacksonModule.java>`_ implementation to list of additional Jackson modules by overriding and implementing the `ScalaObjectMapperModule#additionalJacksonModules`.
 
 For example: first create the serializer or deserializer (a deserializer example is shown below)
 
@@ -355,7 +355,7 @@ features:
 -  Throws a `JsonMappingException` when required fields are missing from the parsed JSON.
 -  Uses specified `case class` default values when fields are missing in the incoming JSON.
 -  Properly deserializes a `Seq[Long]` (see: https://github.com/FasterXML/jackson-module-scala/issues/62).
--  Supports `"wrapped values" <https://docs.scala-lang.org/overviews/core/value-classes.html>`__ using `c.t.util.jackson.WrappedValue <https://github.com/twitter/util/blob/develop/util-jackson/src/main/scala/com/twitter/util/jackson/WrappedValue.scala>`_.
+-  Supports `"wrapped values" <https://docs.scala-lang.org/overviews/core/value-classes.html>`__ using `c.t.util.jackson.WrappedValue <https://github.com/twitter/util/blob/develop/util-core/src/main/scala/com/twitter/util/WrappedValue.scala>`_.
 -  Support for field and method level validations via integration with the `util-validator <https://twitter.github.io/util/guide/util-validator/index.html>`__ Bean Validation 2.0 style validations during JSON deserialization.
 -  Accumulates all JSON deserialization errors (instead of failing fast) in a returned sub-class of `JsonMappingException` (see: `CaseClassMappingException <https://github.com/twitter/util/blob/develop/util-jackson/src/main/scala/com/twitter/util/jackson/caseclass/exceptions/CaseClassMappingException.scala>`_).
 
@@ -372,11 +372,11 @@ Jackson InjectableValues Support
 --------------------------------
 
 By default, the Finatra provides a |ScalaObjectMapper|_ via the |ScalaObjectMapperModule|_ configured
-to resolve Jackson `InjectableValues <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/InjectableValues.java>`_
+to resolve Jackson `InjectableValues <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/InjectableValues.java>`_
 via a given Google `Guice <https://github.com/google/guice>`_ `Injector <https://google.github.io/guice/api-docs/latest/javadoc/index.html?com/google/inject/Injector.html>`_.
 
 The default is very similar to the `jackson-module-guice <https://github.com/FasterXML/jackson-modules-base/tree/master/guice>`_ --
-`GuiceInjectableValues <https://github.com/FasterXML/jackson-modules-base/blob/master/guice/src/main/java/com/fasterxml/jackson/module/guice/GuiceInjectableValues.java>`_.
+`GuiceInjectableValues <https://github.com/FasterXML/jackson-modules-base/blob/master/guice/src/main/java/tools/jackson/module/guice/GuiceInjectableValues.java>`_.
 
 .. note::
 
@@ -385,7 +385,7 @@ The default is very similar to the `jackson-module-guice <https://github.com/Fas
     value in a deserialized object from somewhere other than the incoming JSON. In Jackson parlance,
     this is “injection” of a value.
 
-The Finatra `c.t.finatra.jackson.caseclass.GuiceInjectableValues <https://github.com/twitter/util/blob/develop/util-jackson/src/main/scala/com/twitter/util/jackson/caseclass/GuiceInjectableValues.scala>`_
+The Finatra `c.t.finatra.jackson.caseclass.GuiceInjectableValues <https://github.com/twitter/finatra/blob/release/jackson/src/main/scala/com/twitter/finatra/jackson/caseclass/GuiceInjectableValues.scala>`_
 allows users to denote fields in the case class to fill with values that come from a configured Google `Guice <https://github.com/google/guice>`_
 `Injector <https://google.github.io/guice/api-docs/latest/javadoc/index.html?com/google/inject/Injector.html>`_
 such that you can do this:
@@ -407,7 +407,7 @@ the mapper was configured. In this case, the framework would attempt to obtain a
 from the object graph.
 
 As mentioned, this is essentially the same functionality found in the `jackson-module-guice <https://github.com/FasterXML/jackson-modules-base/tree/master/guice>`__
-`GuiceInjectableValues <https://github.com/FasterXML/jackson-modules-base/blob/master/guice/src/main/java/com/fasterxml/jackson/module/guice/GuiceInjectableValues.java>`__
+`GuiceInjectableValues <https://github.com/FasterXML/jackson-modules-base/blob/master/guice/src/main/java/tools/jackson/module/guice/GuiceInjectableValues.java>`__
 with a key difference being that the Finatra version ensures we do not attempt lookup of a field from
 the Guice Injector **unless there is a non-null Guice Injector configured and the field is specifically annotated**
 with one of the supporting annotations.
@@ -503,9 +503,9 @@ ensure usage of a consistently configured mapper across your application.
 Implement via a Custom |ScalaObjectMapperModule|_
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- First, create a new Jackson `com.fasterxml.jackson.databind.Module <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/Module.java>`__ implementation. You can use the `com.fasterxml.jackson.databind.module.SimpleModule <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/module/SimpleModule.java>`_.
+- First, create a new Jackson `com.fasterxml.jackson.databind.JacksonModule <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/JacksonModule.java>`__ implementation. You can use the `com.fasterxml.jackson.databind.module.SimpleModule <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/module/SimpleModule.java>`_.
 - Add your `MixIn` using the `SimpleModule#setMixInAnnotation` method in your module.
-- In your custom |ScalaObjectMapperModule|_ extension, add the Jackson `Module <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/Module.java>`__.
+- In your custom |ScalaObjectMapperModule|_ extension, add the `JacksonModule <https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/tools/jackson/databind/JacksonModule.java>`__.
 
 For example, create a new Jackson `SimpleModule`: