]>
Commit | Line | Data |
---|---|---|
f67539c2 TL |
1 | /* |
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 | |
9 | * | |
10 | * http://www.apache.org/licenses/LICENSE-2.0 | |
11 | * | |
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 | |
17 | * under the License. | |
18 | */ | |
19 | ||
20 | # Thrift Tutorial | |
21 | # Mark Slee (mcslee@facebook.com) | |
22 | # | |
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. | |
27 | # | |
28 | # Before running this file, you will need to have installed the thrift compiler | |
29 | # into /usr/local/bin. | |
30 | ||
31 | /** | |
32 | * The first thing to know about are types. The available types in Thrift are: | |
33 | * | |
34 | * bool Boolean, one byte | |
35 | * byte Signed 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 | |
40 | * string String | |
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 | |
45 | * | |
46 | * Did you also notice that Thrift supports C style comments? | |
47 | */ | |
48 | ||
49 | // Just in case you were wondering... yes. We support simple C comments too. | |
50 | ||
51 | /** | |
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. | |
55 | * | |
56 | * Included objects are accessed using the name of the .thrift file as a | |
57 | * prefix. i.e. shared.SharedObject | |
58 | */ | |
59 | include "shared.thrift" | |
60 | ||
61 | /** | |
62 | * Thrift files can namespace, package, or prefix their output in various | |
63 | * target languages. | |
64 | */ | |
65 | namespace cpp tutorial | |
66 | namespace java tutorial | |
67 | namespace php tutorial | |
68 | namespace perl tutorial | |
69 | namespace smalltalk.category Thrift.Tutorial | |
70 | ||
71 | /** | |
72 | * Thrift lets you do typedefs to get pretty names for your types. Standard | |
73 | * C style here. | |
74 | */ | |
75 | typedef i32 MyInteger | |
76 | ||
77 | /** | |
78 | * Thrift also lets you define constants for use across languages. Complex | |
79 | * types and structs are specified using JSON notation. | |
80 | */ | |
81 | const i32 INT32CONSTANT = 9853 | |
82 | const map<string,string> MAPCONSTANT = {'hello':'world', 'goodnight':'moon'} | |
83 | ||
84 | /** | |
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. | |
87 | */ | |
88 | enum Operation { | |
89 | ADD = 1, | |
90 | SUBTRACT = 2, | |
91 | MULTIPLY = 3, | |
92 | DIVIDE = 4 | |
93 | } | |
94 | ||
95 | /** | |
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. | |
99 | * | |
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. | |
103 | */ | |
104 | struct Work { | |
105 | 1: i32 num1 = 0, | |
106 | 2: i32 num2, | |
107 | 3: Operation op, | |
108 | 4: optional string comment, | |
109 | } | |
110 | ||
111 | /** | |
112 | * Structs can also be exceptions, if they are nasty. | |
113 | */ | |
114 | exception InvalidOperation { | |
115 | 1: i32 what, | |
116 | 2: string why | |
117 | } | |
118 | ||
119 | /** | |
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. | |
122 | */ | |
123 | service Calculator extends shared.SharedService { | |
124 | ||
125 | /** | |
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. | |
130 | */ | |
131 | ||
132 | void ping(), | |
133 | ||
134 | i32 add(1:i32 num1, 2:i32 num2), | |
135 | ||
136 | i32 calculate(1:i32 logid, 2:Work w) throws (1:InvalidOperation ouch), | |
137 | ||
138 | /** | |
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 | |
141 | * must be void. | |
142 | */ | |
143 | oneway void zip() | |
144 | ||
145 | } | |
146 | ||
147 | /** | |
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. | |
152 | */ |