c101867e.5628b7ba.js

(window.webpackJsonp=window.webpackJsonp||[]).push([[39],{107:function(e,n,t){"use strict";t.r(n),t.d(n,"frontMatter",(function(){return s})),t.d(n,"metadata",(function(){return c})),t.d(n,"toc",(function(){return p})),t.d(n,"default",(function(){return m}));var a=t(3),r=t(7),i=(t(0),t(119)),o=["components"],s={title:"Writing generic code",sidebar_label:"Generic programming",layout:"docs"},c={unversionedId:"generic",id:"generic",isDocsHomePage:!1,title:"Writing generic code",description:"In some cases you will want to write generic code that can handle arbitrary",source:"@site/../docs/target/mdoc/generic.md",slug:"/generic",permalink:"/docs/generic",version:"current",sidebar_label:"Generic programming",sidebar:"someSidebar",previous:{title:"Validating Protobufs",permalink:"/docs/validation"},next:{title:"Writing protoc plugins in Scala",permalink:"/docs/writing-plugins"}},p=[{value:"Generated types",id:"generated-types",children:[]},{value:"Writing a function that accepts any message type",id:"writing-a-function-that-accepts-any-message-type",children:[]},{value:"Summoning the companion",id:"summoning-the-companion",children:[]}],l={toc:p};function m(e){var n=e.components,t=Object(r.a)(e,o);return Object(i.b)("wrapper",Object(a.a)({},l,t,{components:n,mdxType:"MDXLayout"}),Object(i.b)("p",null,"In some cases you will want to write generic code that can handle arbitrary\nmessage types. This guide will show you various techniques that you can use\nto accomplish that."),Object(i.b)("h2",{id:"generated-types"},"Generated types"),Object(i.b)("p",null,"For each message in your proto files, ScalaPB will generate a case class which\nextends the ",Object(i.b)("inlineCode",{parentName:"p"},"GeneratedMessage[MessageType]")," and a companion object:"),Object(i.b)("pre",null,Object(i.b)("code",{parentName:"pre",className:"language-scala"},"case class MyMessage(...) extends scalapb.GeneratedMessage\n\nobject MyMessage extends scalapb.generatedMessageCompanion[MyMessage]\n")),Object(i.b)("p",null,"Generally speaking, the case class would have methods that act on a given\ninstance. Here are the important ones:"),Object(i.b)("pre",null,Object(i.b)("code",{parentName:"pre",className:"language-scala"},"trait GeneratedMessage {\n  // Serializes this message to the given output stream.\n  def writeTo(output: OutputStream): Unit\n  \n  // Serializes this message into an array of bytes\n  def toByteArray: Array[Byte] = {\n\n  // Returns the companion object of this message.\n  def companion: GeneratedMessageCompanion[_]\n\n  // Returns a proto string representation of this message.\n  def toProtoString: String\n}\n")),Object(i.b)("p",null,"The companion, in turn, provides methods to create new instances of the type,\nas well as retrieving the descriptors of the messages. The descriptors can be\nused to query structural information about the proto files at runtime. Note\nthat the ",Object(i.b)("inlineCode",{parentName:"p"},"GeneratedMessageCompanion")," takes a type parameter ",Object(i.b)("inlineCode",{parentName:"p"},"A")," which\nrepresents the message case class (must be a subtype of ",Object(i.b)("inlineCode",{parentName:"p"},"GeneratedMessage"),"):"),Object(i.b)("pre",null,Object(i.b)("code",{parentName:"pre",className:"language-scala"},"trait GeneratedMessageCompanion[A <: GeneratedMessage] {\n  // Parses a message of type A from a byte array.\n  def parseFrom(s: Array[Byte]): A\n\n  // Returns the Java descriptors\n  def javaDescriptor: com.google.protobuf.Descriptors.Descriptor\n\n  // Returns the Scala descriptors\n  def scalaDescriptor: scalapb.descriptors.Descriptor\n\n  // Returns the companion for a field. The field must be a message field.\n  def messageCompanionForFieldNumber(field: Int): GeneratedMessageCompanion[_]\n}\n")),Object(i.b)("h2",{id:"writing-a-function-that-accepts-any-message-type"},"Writing a function that accepts any message type"),Object(i.b)("p",null,"The following is an example of a function that takes an instance of a message\nand writes it to a file."),Object(i.b)("pre",null,Object(i.b)("code",{parentName:"pre",className:"language-scala"},"import java.nio.file.{Files, Paths}\nimport scalapb.GeneratedMessage\n\ndef writeToFile[A <: GeneratedMessage](msg: A, fileName: String): Unit = {\n  Files.write(Paths.get(fileName), msg.toByteArray)\n  ()\n}\n")),Object(i.b)("h2",{id:"summoning-the-companion"},"Summoning the companion"),Object(i.b)("p",null,"In our next example, we will write a function that reads a file and parse it\ninto a message of type ",Object(i.b)("inlineCode",{parentName:"p"},"A"),". To build a new instance of a message, we need to\ncall ",Object(i.b)("inlineCode",{parentName:"p"},"parseFrom")," on the companion. Using Scala's implicit search, it is easy\nto obtain the companion of any message type:"),Object(i.b)("pre",null,Object(i.b)("code",{parentName:"pre",className:"language-scala"},"import java.nio.file.{Files, Paths}\nimport scalapb.{GeneratedMessage, GeneratedMessageCompanion}\n\ndef readFromFile[A <: GeneratedMessage](fileName: String)(\n  implicit cmp: GeneratedMessageCompanion[A]): A = {\n    val byteArray = Files.readAllBytes(Paths.get(fileName))\n    cmp.parseFrom(byteArray)\n}\n")),Object(i.b)("p",null,"When calling this function, you need to provide the specific type you want it\nto return, and the filename. The Scala compiler will automatically find the\nappropriate message companion to pass as ",Object(i.b)("inlineCode",{parentName:"p"},"cmp")," via implicit search:"),Object(i.b)("pre",null,Object(i.b)("code",{parentName:"pre",className:"language-scala"},'readFromFile[Person]("/tmp/person.pb")\n')))}m.isMDXComponent=!0},119:function(e,n,t){"use strict";t.d(n,"a",(function(){return m})),t.d(n,"b",(function(){return g}));var a=t(0),r=t.n(a);function i(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function o(e,n){var t=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);n&&(a=a.filter((function(n){return Object.getOwnPropertyDescriptor(e,n).enumerable}))),t.push.apply(t,a)}return t}function s(e){for(var n=1;n<arguments.length;n++){var t=null!=arguments[n]?arguments[n]:{};n%2?o(Object(t),!0).forEach((function(n){i(e,n,t[n])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(t)):o(Object(t)).forEach((function(n){Object.defineProperty(e,n,Object.getOwnPropertyDescriptor(t,n))}))}return e}function c(e,n){if(null==e)return{};var t,a,r=function(e,n){if(null==e)return{};var t,a,r={},i=Object.keys(e);for(a=0;a<i.length;a++)t=i[a],n.indexOf(t)>=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a<i.length;a++)t=i[a],n.indexOf(t)>=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var p=r.a.createContext({}),l=function(e){var n=r.a.useContext(p),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},m=function(e){var n=l(e.components);return r.a.createElement(p.Provider,{value:n},e.children)},u={inlineCode:"code",wrapper:function(e){var n=e.children;return r.a.createElement(r.a.Fragment,{},n)}},d=r.a.forwardRef((function(e,n){var t=e.components,a=e.mdxType,i=e.originalType,o=e.parentName,p=c(e,["components","mdxType","originalType","parentName"]),m=l(t),d=a,g=m["".concat(o,".").concat(d)]||m[d]||u[d]||i;return t?r.a.createElement(g,s(s({ref:n},p),{},{components:t})):r.a.createElement(g,s({ref:n},p))}));function g(e,n){var t=arguments,a=n&&n.mdxType;if("string"==typeof e||a){var i=t.length,o=new Array(i);o[0]=d;var s={};for(var c in n)hasOwnProperty.call(n,c)&&(s[c]=n[c]);s.originalType=e,s.mdxType="string"==typeof e?e:a,o[1]=s;for(var p=2;p<i;p++)o[p]=t[p];return r.a.createElement.apply(null,o)}return r.a.createElement.apply(null,t)}d.displayName="MDXCreateElement"}}]);