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:
- Work well with Scala and the Typesafe libraries.
- Work independently from the others.
- Be well defined in their functionality.
- Minimize the number of external dependencies.
- 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
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
andMockActor
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 anActorSystem
,ActorRefFactory
, andExecutionContext
. 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
providesval config
which uses Typesafe's ConfigFactory to load configuration files. Typically this will beapplication.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 wrapJsonUtil.toJson
andJsonUtil.fromJson
. If youimport com.paypal.cascade.json._
you can decode aString
using.fromJson[T]
and you can encode anAny
(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.
- Create an account at http://issues.sonatype.org
- Request publish access at https://issues.sonatype.org/browse/OSSRH-11183
- Create an account at http://oss.sonatype.org
- 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
- 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>)
- 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
- 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.
- Complete the steps in the "Publishing to Sonatype OSS" section above
- Create a
release/$RELEASENAME
branch - Open a pull request merging your branch from (2) into
master
- 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"
- Go to http://oss.sonatype.org and login
- Go to βStaging Repositoriesβ (on left side)
- Find your repo (at the bottom)β¨
- Click close
- Click release
- Merge your PR from (3), then merge
release/$RELEASENAME
intodevelop
THIS FILE WAS AUTO GENERATED BY THE README TEMPLATE. DO NOT EDIT DIRECTLY.