2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
21 # Mark Slee (mcslee@facebook.com)
23 # This file aims to teach you how to use Thrift, in a .thrift file. Neato. The
24 # first thing to notice is that .thrift files support standard shell comments.
25 # This lets you make your thrift file executable and include your Thrift build
26 # step on the top line. And you can place comments like this anywhere you like.
28 # Before running this file, you will need to have installed the thrift compiler
29 # into /usr/local/bin.
32 * The first thing to know about are types. The available types in Thrift are:
34 * bool Boolean, one byte
36 * i16 Signed 16-bit integer
37 * i32 Signed 32-bit integer
38 * i64 Signed 64-bit integer
39 * double 64-bit floating point value
41 * binary Blob (byte array)
42 * map<t1,t2> Map from one type to another
43 * list<t1> Ordered list of one type
44 * set<t1> Set of unique elements of one type
46 * Did you also notice that Thrift supports C style comments?
49 // Just in case you were wondering... yes. We support simple C comments too.
52 * Thrift files can reference other Thrift files to include common struct
53 * and service definitions. These are found using the current path, or by
54 * searching relative to any paths specified with the -I compiler flag.
56 * Included objects are accessed using the name of the .thrift file as a
57 * prefix. i.e. shared.SharedObject
59 include "shared.thrift"
62 * Thrift files can namespace, package, or prefix their output in various
65 namespace cpp tutorial
66 namespace java tutorial
67 namespace php tutorial
68 namespace perl tutorial
69 namespace smalltalk.category Thrift.Tutorial
72 * Thrift lets you do typedefs to get pretty names for your types. Standard
78 * Thrift also lets you define constants for use across languages. Complex
79 * types and structs are specified using JSON notation.
81 const i32 INT32CONSTANT = 9853
82 const map<string,string> MAPCONSTANT = {'hello':'world', 'goodnight':'moon'}
85 * You can define enums, which are just 32 bit integers. Values are optional
86 * and start at 1 if not supplied, C style again.
96 * Structs are the basic complex data structures. They are comprised of fields
97 * which each have an integer identifier, a type, a symbolic name, and an
98 * optional default value.
100 * Fields can be declared "optional", which ensures they will not be included
101 * in the serialized output if they aren't set. Note that this requires some
102 * manual management in some languages.
108 4: optional string comment,
112 * Structs can also be exceptions, if they are nasty.
114 exception InvalidOperation {
120 * Ahh, now onto the cool part, defining a service. Services just need a name
121 * and can optionally inherit from another service using the extends keyword.
123 service Calculator extends shared.SharedService {
126 * A method definition looks like C code. It has a return type, arguments,
127 * and optionally a list of exceptions that it may throw. Note that argument
128 * lists and exception lists are specified using the exact same syntax as
129 * field lists in struct or exception definitions.
134 i32 add(1:i32 num1, 2:i32 num2),
136 i32 calculate(1:i32 logid, 2:Work w) throws (1:InvalidOperation ouch),
139 * This method has a oneway modifier. That means the client only makes
140 * a request and does not listen for any response at all. Oneway methods
148 * That just about covers the basics. Take a look in the test/ folder for more
149 * detailed examples. After you run this file, your generated code shows up
150 * in folders with names gen-<language>. The generated code isn't too scary
151 * to look at. It even has pretty indentation.