Comparison of Providence with Apache Thrift

If you are familiar with Apache Thrift, this is an overview over the main differences in support between the two systems. The differences are mostly minute, but all feature changes are there for a reason. Differences are based on the IDL at thrift.apache.org.

Some features of apache thrift has simply been removed. This is done in order to simplify both the thrift IDL parsing, and the resulting code generator. Note that this is the differences between what is supported and handled by the described IDL. With some few exceptions, all of the added features are simply ignored by the Apache thrift compiler.

In addition to this providence also adds a number of features not supported in apache thrift. Some of these can only be used in .providence files, as they also break the thrift syntax, mainly by adding more keywords that work in different ways than what apache thrift expects.

Annotations

Annotations in apache thrift is simply noted as "something internal to facebook", and should not be used. This includes xsd and some other keywords. Instead of removing annotations, I explicitly use annotations for various type modifications. Note that annotations can only modify what the code generator generates, but are not included in the type descriptors that are generated.

See details on annotations for more.

Namespaces

Apache Thrift supports a couple of special "namespace" declarations, e.g. php_namespace and xsi_namespace. They have been deprecated in thrift, but are entirely removed from providence, so the keywords are not recognized at all, and will fail parsing of the thrift file.

Void methods in services

Since Apache Thrift v0.11.0, using void return type in methods between Providence and Apache Thrift stopped working. This is because Apache Thrift decided to remove the implicit 0: void success field from the generated response message and recently even started failing if the field was present.

IMHO This is bad protocol design as it creates a false success scenario on a service method call if an exception is added to the call, and the server side is updated, but the client is not. If the server throw the new exception the exception is ignored when parsing the response, and the client believes the call was a success because there was no exception set.

Because of this, this change in Apache Thrift has not been ported to providence. You should change your service calls to use a known return type instead of void if this problem is encountered.

Naming Conflicts

Each code generator needs make getters, setters and mutators using names that are compatible with the language AND compliant to standard styleguides for that language. By using prefixes and name modifications consistently this can be done with some restrictions in order to enable most 'names' to be allowed all over the place.

E.g. the field name 'public' should be allowed for all languages, including java and C++ where it is a reserved word.

Since some languages prefer camelCased names, and other prefer c_cased names, there should be no fields in the same struct with names that will conflict if all '_' are removed, and the entire name is lower-cased. Even though it is a little more complicated than that.

For this to work in Java, we apply the rules:

• All names are camelCased with a prefix for all methods and fields. E.g. value fields are prefixed mValue, getters with getValue, params with pValue etc. No suffixes are used.
• getters and setters are prefixed with set, addTo, get, clear, mutable, has, num etc.

Or in C++ or python. All the names are initially lower c_cased before included in the code.

• C++: field names are suffixed with _. E.g. myField becomes my_field_.
• python: field names are prefixed with __. E.g. myField becomes __my_field.
• getters and setters are prefixed with set_, get_, mutable_, clear_ add_to_, has_ and num_.
• This breaks the somewhat spread convention that C++ getters should not have any prefix or suffix, but it makes it possible to use otherwise reserved words as field names.