| ←Older revision |
Revision as of 09:20, 16 June 2016 |
| Line 67: |
Line 67: |
| | | | |
| | The type information is really compile time only information - e.g. it gets [[erasure|erased]] during execution. Thus the performance of this [[APIDesignPatterns|API Design Pattern]] is the same of plain builder - but rather on relying on runtime [[exception]]s saying something is missing - it co-operates with [[Javac]] to give the users early edit time/compile time error indications. | | The type information is really compile time only information - e.g. it gets [[erasure|erased]] during execution. Thus the performance of this [[APIDesignPatterns|API Design Pattern]] is the same of plain builder - but rather on relying on runtime [[exception]]s saying something is missing - it co-operates with [[Javac]] to give the users early edit time/compile time error indications. |
| | + | |
| | + | === Initially Initialized === |
| | + | |
| | + | Of course, there can be other factory methods that can create the [[builder]] in a state that is already initialized. For example, if we create a {{truffle|com/oracle/truffle/api/source|Source}} from a real file on disk, we can ask the [[OS]] to guess the MIME type for us: |
| | + | |
| | + | <source lang="java"> |
| | + | public static Builder<Source> fromFile({{JDK|java/io|File}} file) { /* ... */ } |
| | + | |
| | + | // use it as |
| | + | Source src = Builder.fromFile(new File("c:\\x.js")).build(); |
| | + | </source> |
| | + | |
| | + | There can be a mixture of such ''finished'' or ''unfinished'' [[builder]] factory methods in the same class. |
| | | | |
| | === Drawbacks === | | === Drawbacks === |
| | | | |
| | There can be only a single return type in [[Java]]. As such this [[APIDesignPatterns|API pattern]] only works for a single ''essential'' [[builder]] property. One starts in the {{JDK|java/lang|Void}}-state and once it is set one changes the return type to the real one ({{truffle|com/oracle/truffle/api/source|Source}} in the previous case). This trick cannot be repeated more than once. | | There can be only a single return type in [[Java]]. As such this [[APIDesignPatterns|API pattern]] only works for a single ''essential'' [[builder]] property. One starts in the {{JDK|java/lang|Void}}-state and once it is set one changes the return type to the real one ({{truffle|com/oracle/truffle/api/source|Source}} in the previous case). This trick cannot be repeated more than once. |
| | + | |
| | + | |
| | + | Sometimes it makes sense to mix the [[BuilderUnfinished]] pattern with [[BuilderWithConditionalException]]. Then you end up with a [[builder]] with two generic types. That doesn't support [[cluelessness]] either - in general [[clueless]] programmers are scared by generics. On the other hand, in the typical usage, the generics aren't visible: |
| | + | |
| | + | <source lang="lang"> |
| | + | Source src = Builder.newFromText("function hello() { print 'Hello'; }"). |
| | + | name("hello.js"). |
| | + | mimeType("text/javascript"). |
| | + | build(); |
| | + | </source> |
| | | | |
| | The other problem is error reporting. The classical error is: | | The other problem is error reporting. The classical error is: |
| | Result of build() method cannot be assigned to src. Expecting ({{truffle|com/oracle/truffle/api/source|Source}} got {{JDK|java/lang|Void}} | | Result of build() method cannot be assigned to src. Expecting ({{truffle|com/oracle/truffle/api/source|Source}} got {{JDK|java/lang|Void}} |
| | This is a perfect indication that something is wrong. However the fix (e.g. one has to call '''mimetype''' method) first isn't completely obvious from the error message. [[Good]] [[Javadoc]] on the [[builder]] [[factory]] method or the '''build()''' method itself can fix that - however this is not as [[clueless]] solution is we might want. | | This is a perfect indication that something is wrong. However the fix (e.g. one has to call '''mimetype''' method) first isn't completely obvious from the error message. [[Good]] [[Javadoc]] on the [[builder]] [[factory]] method or the '''build()''' method itself can fix that - however this is not as [[clueless]] solution is we might want. |
| - |
| |
| - |
| |
| | | | |
| | | | |