ScalaPB File-level Options
ScalaPB file-level options lets you
- specify the name of the Scala package to use (the default is using the java package name).
- request that ScalaPB will not append the protofile name to the package name.
- specify Scala imports so custom base traits and custom types (see below) do not require the full class name.
The file-level options are not required, unless you are interested in those customizations. If you do not want to customize the defaults, you can safely skip this section.
package_namesets the Scala base package name, if this is not defined, then it falls back to
java_packageand then to
flat_packageto true (default is
false) makes ScalaPB not append the protofile base name to the package name. You can also apply this option globally to all files by adding it to your ScalaPB SBT Settings.
single_fileoption makes the generator output all messages and enums to a single Scala file.
preambleis a list of strings that is output at the top of the generated Scala file. This option requires
single_fileto be set. It is commonly used to define sealed traits that are extended using
(scalapb.message).extends- see custom base traits below and this example.
primitive_wrappers option is useful when you want to have optional
primitives in Proto 3, for example
Option[Int]. In proto 3, unlike proto 2,
primitives are not wrapped in an option by default. The standard technique to
obtain an optional primitive is to wrap it inside a message (since messages
are provided inside an
Option). Google provides standard wrappers to the
primitive types in
primitive_wrappers is enabled by default for ScalaPB>=0.6.0. Whenever one
of the standard wrappers is used, it will be mapped to
is a primitive type. For example:
To disable primitive wrappers in a file:
In versions of ScalaPB prior to 0.6.0, primitive wrappers had to be turned on manually in each file:
Custom base traits for messages
Note: this option is available in ScalaPB 0.6.1 and later.
ScalaPBs allows you to specify custom base traits to a generated case class. This is useful when you have a few messages that share common fields and you would like to be able to access those fields through a single trait.
In your code, define the base trait
DomainEvent and include any subset of the fields:
You can specify any number of base traits for a message.
It is also possible to make the generated companion classes extend a class
or trait, by using the
companion_extends option. For example:
Will generate a case class that extends
MySuperClass, and the companion
object will extend
Custom base traits for enums
In a similar fashion to custom base traits for messages, it is possible to define custom base traits for enum types, for the companion objects of enum types and even for specific values.
The generated code will look something like this:
You can customize the Scala type of any field. One use-case for this is when
you would like to use type-safe wrappers around primitive values to enforce unit
correctness. For example, instead of using a raw integer for time fields, you can
wrap them in a
We would like to write code like this:
How will ScalaPB know how to convert from the original type (
Integer) to the
Seconds? For each custom type you need to define an implicit
TypeMapper that will tell ScalaPB how to convert between the custom type and
the base Scala type. A good place to define this implicit is in the companion
class for your custom type, since the Scala compiler will look for a
typemapper there by default. If your typemapper is defined elsewhere, you
will need to import it manually by using the
import file-level option.
TypeMapper takes two function parameters. The first converts from the original type to
the custom type. The second function converts from the custom type to the
In addition to primitive values, you can customize enums and messages as well.
For more examples, see:
Custom types on maps
Since version 0.6.0 it is possible to customize the key and value types of
maps. Like the custom types described above you will need to have a
for the custom type.
CustomMaps in maps.proto
Custom collection types
By default, ScalaPB compiles repeated fields into a
Seq[T]. When a message
is parsed from bytes, the default implementation generates a
which is a subtype of
Seq[T]. You can instruct ScalaPB to use a different
collection type for a file, or just for one repeated field. If both are
defined then the field-level setting wins.
Array is not supported along with Java conversions.
Note: Most Scala collections can be used with this feature. If you are trying
to implement your own collection type, it may be useful to check
the simplest custom collection that is compatible with ScalaPB:
Sometimes it may be useful to manually specify the name of a field in the
generated code. For example, if you have a field named
hash_code, then the
camel-case version of it would be
hashCode. Since that name would conflict with
we inherit from Java, ScalaPB issues an error. You can tell ScalaPB to use an
alternative name by using the
Since ScalaPB 0.6.3, you can add annotations to the generated case classes like this:
Adding scalapb.proto to your project
The easiest way to get
protoc to find
scalapb/scalapb.proto when compiling
through SBT is by adding the following to your
libraryDependencies += "com.trueaccord.scalapb" %% "scalapb-runtime" % com.trueaccord.scalapb.compiler.Version.scalapbVersion % "protobuf"
If you are invoking
protoc manually, you will need to ensure that the files in
directory are available to your project.