README.md

Cascade

Cascade is a collection of libraries that implement common patterns, convenience objects, implicit classes, utilities, and other foundational pieces used in Scala applications and servers at PayPal. The libraries herein are carefully designed to:

1. Work well with Scala and the Typesafe libraries.
2. Work independently from the others.
3. Be well defined in their functionality.
4. Minimize the number of external dependencies.
5. Related to (4) - use the features of the Scala standard library before building their own.

Getting Started

To use Cascade libraries in your project, simply add a dependency to your build system. In an SBT project, add the following to your build.sbt or Build.scala file:

"com.paypal" %% "cascade-$projectName" % "0.5.1"

For example, to use the Akka library:

"com.paypal" %% "cascade-akka" % "0.5.1"

If you're starting a new project, we recommend using SBT along with Horizon

Usage

The libraries live in separate sub-projects in this repository:

• common - utilities to help build any Scala program.
• http - building blocks for building Spray servers.
• akka - building blocks for building Akka systems.
• json - utilities to encode/decode JSON.

As mentioned in (2) above, these libraries are designed to work independently. Although they have internal dependencies on each other (e.g. many libraries depend on common), you can mix and match which libraries you use.

The libraries in Cascade all follow some similar patterns. PATTERNS.md describes them in detail.

Current Version: 0.5.1

View the ScalaDocs

Dependencies

To use Cascade libraries in your project, simply add a dependency to your build system. In an SBT project, add the following to your build.sbt or Build.scala file:

"com.paypal" %% "cascade-$projectName" % "0.5.1"

For example, to use the Akka library:

"com.paypal" %% "cascade-akka" % "0.5.1"

If you're starting a new project, we recommend using SBT along with Horizon

The Libraries

common

Basic patterns, objects, and utilities for any project:

• CascadeApp is the starting place for building executable applications. It sets up logging and MDC values.
• LoggingSugar provides easy access to SLF4J.
• trys package object contains implicit classes/methods to convert Try objects to Either and Future objects.
• option package object contains implicit classes/methods to wrap any object in an Option.
• casts package object contains implicit classes/methods to cast objects to the class type provided.

Useful test objects include:

• ActorSpecification and MockActor for testing Akka actors.
• The scalacheck package object for extensions to Scalacheck.

http

The http library has base objects and traits for creating Spray HTTP servers. This library is intended to complement the functionality that Spray and Akka already have. Please see our getting started guide and detailed documentation for more.

akka

• CommonActor is a skeleton for building Akka actors. It provides logging during an actor's lifecycle and appropriately structure unhandled messages.
• ActorSystemWrapper provides a singleton interface to an ActorSystem, ActorRefFactory, and ExecutionContext. It also adds a reasonable default shutdown hook.
• config package object provides an implicit class to get configuration values. It wraps Typesafe's Config getter methods in Options.
• ConfigWrapper provides val config which uses Typesafe's ConfigFactory to load configuration files. Typically this will be application.conf.

json

Simple functionality for fast JSON encoding/decoding that uses Jackson under the hood.

• The JsonUtil object provides two functions to do encoding and decoding:
  • toJson(value: Any): Try[String]
  • `fromJson[T: Manifest](json: String): Try[T]``
• The json package object provides implicit classes to wrap JsonUtil.toJson and JsonUtil.fromJson. If you import com.paypal.cascade.json._ you can decode a String using .fromJson[T] and you can encode an Any (any type) using .toJson.

Contributing

As normal, if you want to contribute to Cascade, we gladly accept pull requests. Simply fork this repository, make your changes, and submit a PR to us. If you are fixing an issue in your PR, please make sure to write Fixes #123 in the description, so that the issue is closed after your PR gets merged.

Note: If you want to modify this file (README.md) in your PR, edit Readme-Template.md and then run genReadme in SBT.

Development

If you have Vagrant, simply vagrant up in this project to get a VM with all the necessary tools for development. When inside the VM, the sources for this project are inside /vagrant, and they're synched with your host machine. Edit your code on the host machine and build/run it inside the VM.

If you don't have Vagrant, you'll need Scala 2.11.6 and SBT 0.13.8 to build and run this project.

Publishing to Sonatype OSS

This section is for Cascade core contributors only.

The following should be done once prior to attempting to release a new version of Cascade.

1. Create an account at http://issues.sonatype.org
2. Request publish access at https://issues.sonatype.org/browse/OSSRH-11183
3. Create an account at http://oss.sonatype.org
4. Create a user token:

• Login into Sonatype OSS with the credentials from the previous step
• Open up your profile
• Select user token from the profile settings dropdown
• Click access user token

5. Create ~/.sbt/0.13/sonatype.sbt using the user token from the previous step:

credentials += Credentials("Sonatype Nexus Repository Manager", "oss.sonatype.org", <username>, <password>)

6. If you haven't done so previously, open sbt in Cascade to create and publish a PGP key pair using these commands:

• set pgpReadOnly := false
• pgp-cmd gen-key. Take note of the email address you set. You'll use it in the next command.
• pgp-cmd send-key $EMAILADDR hkp://keyserver.ubuntu.com
• See http://www.scala-sbt.org/sbt-pgp/usage.html for more information

7. Close sbt in Cascade

Releasing A New Version of Cascade

This section is for Cascade core contributors only.

All releases must be done from a release branch that merges into master.

1. Complete the steps in the "Publishing to Sonatype OSS" section above
2. Create a release/$RELEASENAME branch
3. Open a pull request merging your branch from (2) into master
4. Perform the release:

• Set the CHANGELOG_MSG and CHANGELOG_AUTHOR environment variables to work around an issue with sbt 0.13.6+
• sbt "release with-defaults"

5. Go to http://oss.sonatype.org and login
6. Go to “Staging Repositories” (on left side)
7. Find your repo (at the bottom)

8. Click close
9. Click release
10. Merge your PR from (3), then merge release/$RELEASENAME into develop

THIS FILE WAS AUTO GENERATED BY THE README TEMPLATE. DO NOT EDIT DIRECTLY.