Skip to content
This repository

Added a TUTORIAL.md on how to add functionality to the boostrapper-generated service. #7

Merged
merged 7 commits into from about 3 years ago

3 participants

dloft Robey Pointer Kyle Maxwell
dloft
Collaborator
dloft commented

Reviewed by fizx and robey.

Robey Pointer robey commented on the diff
scala-bootstrapper.gemspec
((14 lines not shown))
20 20 ]
21 21 s.files = [
22 22 ".document",
23   - ".gitignore",
1
Robey Pointer
robey added a note

we should probably keep .gitignore, though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Robey Pointer
robey commented

+1!

Kyle Maxwell fizx merged commit 2002a29 into from
Kyle Maxwell fizx closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
18 README.rdoc
Source Rendered
... ... @@ -1,8 +1,18 @@
1 1 This creates a standard environment for your twitter-centric sbt/scala thrift service.
2 2
  3 +Building:
  4 +
  5 + :$ rake build
  6 + :$ gem install pkg/scala-bootstrapper-*.gem
  7 +
3 8 Usage:
4 9
5   - :$ mkdir foo
6   - :$ cd foo
7   - :$ scala-bootstrapper foo
8   - :$ sbt update test
  10 + :$ mkdir birdname
  11 + :$ cd birdname
  12 + :$ scala-bootstrapper birdname
  13 + :$ sbt update test
  14 +
  15 +Tutorial:
  16 +
  17 + :$ less TUTORIAL.md
  18 +
2  VERSION
... ... @@ -1 +1 @@
1   -0.9.1
  1 +0.9.2
14 lib/template/README.md
Source Rendered
... ... @@ -0,0 +1,14 @@
  1 +# Project BirdName
  2 +
  3 +Welcome to your birdname project! To make sure things are working
  4 +properly, you may want to:
  5 +
  6 + $ sbt update test
  7 +
  8 +There is a tutorial for what to do next, which you can find in the
  9 +scala-bootstrapper README.rdoc file.
  10 +
  11 +# Documenting your project
  12 +
  13 +Add documentation here! Eventually, you'll be able to publish this to
  14 +a web site for the world to easily find and read.
162 lib/template/TUTORIAL.md
Source Rendered
... ... @@ -0,0 +1,162 @@
  1 +# Welcome to BirdName!
  2 +
  3 +## Setup
  4 +
  5 +Scala-bootstrapper has created a fully-functional Scala service for
  6 +you. You can verify that things are set up correctly by doing:
  7 +
  8 + $ sbt update test
  9 +
  10 +## Tutorial
  11 +
  12 +### Run your service!
  13 +
  14 +There are two ways to start your service. You can build a runnable
  15 +jar and tell java to run it directly:
  16 +
  17 + $ sbt package-dist
  18 + $ java -Dstage=development -jar ./dist/birdname/birdname-1.0.0-SNAPSHOT.jar
  19 +
  20 +or you can ask sbt to run your service:
  21 +
  22 + $ sbt 'run -f config/development.scala'
  23 +
  24 +### View the Thrift IDL for your service
  25 +
  26 +The IDL for your service is in src/main/thrift/birdname.thrift. The
  27 +Thrift compiler uses the IDL to generate bindings for various
  28 +languages, making it easy for scripts in those languages to talk to
  29 +your service. More information about Thrift and how to write an IDL
  30 +for your service can be found [here](http://wiki.apache.org/thrift/Tutorial)
  31 +
  32 +### Call your service from ruby
  33 +
  34 +Your service implements simple get() and put() methods. Once you have
  35 +your server running, as above, bring up a different shell and:
  36 +
  37 + $ bundle install
  38 + $ cd birdname
  39 + $ ./src/scripts/console
  40 + $ $client
  41 + $ $client.put("key1", "valueForKey")
  42 + $ $client.get("key1")
  43 +
  44 +### Look at the stats for your service
  45 +
  46 +By default, your project is configured to use
  47 +[Ostrich](https://github.com/twitter/ostrich), a library for service
  48 +configuration, administration, and stats reporting. Your config file
  49 +in config/development.scala defines which port ostrich uses for admin
  50 +requests. You can view the stats via that port:
  51 +
  52 + $ curl localhost:9900/stats.txt
  53 + counters:
  54 + Nho2/connects: 1
  55 + Nho2/requests: 2
  56 + Nho2/success: 2
  57 + ...
  58 +
  59 +Ostrich also stores historial stats data and can build
  60 +[graphs](http://localhost:9900/graph/) for you.
  61 +
  62 +### View the implementation of get() and put()
  63 +
  64 +Take a look at src/main/scala/com/twitter/birdname/BirdNameServiceImpl.scala.
  65 +
  66 +### Try adding some timers and counters
  67 +
  68 +At the top of BirdNameServiceImpl.scala, add:
  69 +
  70 + import com.twitter.ostrich.stats.Stats
  71 +
  72 +Then inside get():
  73 +
  74 + Stats.incr("birdname.gets")
  75 +
  76 +and inside put():
  77 +
  78 + Stats.incr("birdname.puts")
  79 +
  80 +Then restart your server, talk to the server via console, and check
  81 +your stats:
  82 +
  83 + $ curl localhost:9900/stats.txt
  84 + counters:
  85 + BirdName/connects: 1
  86 + BirdName/requests: 2
  87 + BirdName/success: 2
  88 + birdname.gets: 1
  89 + birdname.puts: 1
  90 +
  91 +You can also time various things that your server is doing, for
  92 +example:
  93 +
  94 + Stats.time("birdname.put.latency") {
  95 + Thread.sleep(10) // so you can see it
  96 + database(key) = value
  97 + }
  98 +
  99 +### Specs: let's add some tests
  100 +
  101 +[Specs](http://code.google.com/p/specs/) is a Behavior-Driven Design
  102 +framework that allows you to write semi-human-readable descriptions of
  103 +how your service should behave and test that those descriptions are
  104 +valid. You already have some Specs code for your project in
  105 +src/test/scala/com/twitter/birdname/BirdNameServiceImpl.scala. Check
  106 +out the existing test and add a new one for the counter functionality
  107 +we just added.
  108 +
  109 + import com.twitter.ostrich.stats.Stats
  110 +
  111 + ...
  112 +
  113 + "verify stats" in {
  114 + val counters = Stats.getCounters
  115 + foofa.put("name", "bluebird")()
  116 + foofa.get("name")() mustEqual "bluebird"
  117 + counters.getOrElse("foofa.gets", 1) must_==1
  118 + counters.getOrElse("foofa.puts", 1) must_==1
  119 + }
  120 +
  121 +TODO: add link to scala school lesson on Specs
  122 +
  123 +### Automatically compile and test your server when you change code
  124 +
  125 +By now you've had to Ctrl-C your server and restart it to get changes
  126 +to show up. This gets a little tiresome. The build tool we are
  127 +using,
  128 +[SBT (simple build tool)](http://code.google.com/p/simple-build-tool/)
  129 +has a console that you can access by just running "sbt" from the
  130 +command line.
  131 +
  132 + $ sbt
  133 + [info] Standard project rules 0.11.4 loaded (2011-03-18).
  134 + [warn] No .svnrepo file; no svn repo will be configured.
  135 + [info] Building project birdname 1.0.0-SNAPSHOT against Scala 2.8.1
  136 + [info] using BirdNameProject with sbt 0.7.4 and Scala 2.7.7
  137 +
  138 +SBT has a wide array of features, but a useful one right now is to
  139 +use the "~ test" command.
  140 +
  141 + > ~ test
  142 +
  143 +The tilde tells SBT to look for changes to your source files and
  144 +re-execute the command when it detects a change.
  145 +
  146 +TODO: add link to scala school lesson on SBT
  147 +
  148 +### Add an admin / dashboard page.
  149 +
  150 +### Add a new dependency to your project, perhaps twitter/util?
  151 +
  152 +### Take a tour of the logs our service is producing.
  153 +
  154 +### Add command-line parameters for your service.
  155 +-D foo=bar
  156 +runtime.arguments.get("foo")
  157 +
  158 +### Storage: let's persist the data in Cassandra!
  159 +
  160 +### Twitter API: let's listen to the Firehose!
  161 +
  162 +### Twitter API: let's fetch some statuses & users & stuff.
62 scala-bootstrapper.gemspec
... ... @@ -1,6 +1,6 @@
1 1 # Generated by jeweler
2 2 # DO NOT EDIT THIS FILE DIRECTLY
3   -# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
  3 +# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
4 4 # -*- encoding: utf-8 -*-
5 5
6 6 Gem::Specification.new do |s|
@@ -9,48 +9,46 @@ Gem::Specification.new do |s|
9 9
10 10 s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
11 11 s.authors = ["Kyle Maxwell"]
12   - s.date = %q{2011-04-11}
  12 + s.date = %q{2011-04-15}
13 13 s.default_executable = %q{scala-bootstrapper}
14 14 s.description = %q{Twitter scala project init}
15 15 s.email = %q{kmaxwell@twitter.com}
16 16 s.executables = ["scala-bootstrapper"]
17 17 s.extra_rdoc_files = [
18 18 "LICENSE",
19   - "README.rdoc"
  19 + "README.rdoc"
20 20 ]
21 21 s.files = [
22 22 ".document",
23   - ".gitignore",
24   - "HACKING",
25   - "LICENSE",
26   - "README.rdoc",
27   - "Rakefile",
28   - "VERSION",
29   - "bin/scala-bootstrapper",
30   - "lib/template/.gitignore",
31   - "lib/template/Capfile",
32   - "lib/template/Gemfile",
33   - "lib/template/config/development.scala.erb",
34   - "lib/template/config/production.scala.erb",
35   - "lib/template/config/staging.scala.erb",
36   - "lib/template/config/test.scala.erb",
37   - "lib/template/project/build.properties",
38   - "lib/template/project/build/BirdNameProject.scala.erb",
39   - "lib/template/project/plugins/Plugins.scala.erb",
40   - "lib/template/run",
41   - "lib/template/src/main/scala/com/twitter/birdname/BirdNameServiceImpl.scala.erb",
42   - "lib/template/src/main/scala/com/twitter/birdname/Main.scala.erb",
43   - "lib/template/src/main/scala/com/twitter/birdname/config/BirdNameServiceConfig.scala.erb",
44   - "lib/template/src/main/thrift/birdname.thrift.erb",
45   - "lib/template/src/scripts/console.erb",
46   - "lib/template/src/scripts/startup.sh",
47   - "lib/template/src/test/scala/com/twitter/birdname/AbstractSpec.scala.erb",
48   - "lib/template/src/test/scala/com/twitter/birdname/BirdNameServiceSpec.scala.erb",
49   - "scala-bootstrapper.gemspec",
50   - "vendor/trollop.rb"
  23 + "HACKING",
  24 + "LICENSE",
  25 + "README.rdoc",
  26 + "Rakefile",
  27 + "VERSION",
  28 + "bin/scala-bootstrapper",
  29 + "lib/template/.gitignore",
  30 + "lib/template/Capfile",
  31 + "lib/template/Gemfile",
  32 + "lib/template/config/development.scala.erb",
  33 + "lib/template/config/production.scala.erb",
  34 + "lib/template/config/staging.scala.erb",
  35 + "lib/template/config/test.scala.erb",
  36 + "lib/template/project/build.properties",
  37 + "lib/template/project/build/BirdNameProject.scala.erb",
  38 + "lib/template/project/plugins/Plugins.scala.erb",
  39 + "lib/template/run",
  40 + "lib/template/src/main/scala/com/twitter/birdname/BirdNameServiceImpl.scala.erb",
  41 + "lib/template/src/main/scala/com/twitter/birdname/Main.scala.erb",
  42 + "lib/template/src/main/scala/com/twitter/birdname/config/BirdNameServiceConfig.scala.erb",
  43 + "lib/template/src/main/thrift/birdname.thrift.erb",
  44 + "lib/template/src/scripts/console.erb",
  45 + "lib/template/src/scripts/startup.sh",
  46 + "lib/template/src/test/scala/com/twitter/birdname/AbstractSpec.scala.erb",
  47 + "lib/template/src/test/scala/com/twitter/birdname/BirdNameServiceSpec.scala.erb",
  48 + "scala-bootstrapper.gemspec",
  49 + "vendor/trollop.rb"
51 50 ]
52 51 s.homepage = %q{http://github.com/fizx/scala-bootstrapper}
53   - s.rdoc_options = ["--charset=UTF-8"]
54 52 s.require_paths = ["lib"]
55 53 s.rubygems_version = %q{1.3.6}
56 54 s.summary = %q{Twitter scala project init}

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.