Improving Java interface

[bherd-rb]

@davidrpugh These are the first steps to improve the Java interface. I first tried to replicate the Scala class structure in Java in order to get the same level of flexibility. I ran into a couple of problems, e.g. related with the implicit parameters in FourHeapOrderBook.empty.

Rather than trying to solve all of these problems, I started to re-implement sandbox.sc in Java in order to see how easy it would be to use the Scala classes directly (see src/main/java/org/economicsl/auctions/Sandbox.java). Surprisingly, that's now rather simple and straightforward. There is still some syntactic clutter (e.g. the '$' characters or the lack of +and - operators), but overall it looks pretty clear. Also, I added a helper class Clearing that encapsulates the conversion of the clearing result into something that's more easily usable in Java.

I haven't integrated the quoting stuff into the sandbox yet and I haven't tested the direct access from within our demonstrator. I'll do that now. But if it turns out that all of that works, then I'm currently inclined to get rid of the previous Java wrapper (JDoubleAuction.java) altogether and use the Scala classes directly.

What do you think? Is the syntax acceptable from a usability perspective? Some of the stuff could certainly be further simplified, e.g. by adding more helper classes similar to Clearing.java.

[davidrpugh]

@bherd-rb This is definitely an improvement and assuming that you can get it working with you simulator then I think we should drop the old Java wrapper in favor of this approach.

A couple thoughts: first I will get rid of the + and - operators (or rather add another method that does the same thing) in order to eliminate that source of clutter from the Java code. Second, I could also make the implicit ordering that need to be passed to the FourHeapOrderBook constructor explicit if that would help. Third, regarding the clearing class, would it be simpler to have a ClearingResult class in Scala rather than my using a Tuple which then has to be converted?

In general, I will see if there is a way that I can structure the Scala code in order to avoid Java users having to call $.MODULE.someMethod.

[davidrpugh]

@bherd-rb There seems to be a lot of cruft involved in created an instance of LimitAskOrder etc on the Java side. I made some changes to the Scala code in order to improve the situation. Now you can create a limit ask order in Java using...

 // Create some single-unit limit ask orders...
LimitAskOrder<GoogleStock> order3 = new LimitAskOrder<>(issuer, 5, google);
LimitAskOrder<GoogleStock> order4 = new LimitAskOrder<>(issuer, 6, google);

...the solution is to create a trait called LimitAskOrderLike which can be used as a mixin to provide LimitAskOrder like behavior to other order types as needed but then create a class LimitAskOrderthat implements theLimitAskOrderLike`trait for simple limit orders.

Does this work for you? If so, then I will open a new PR against the develop branch and make similar changes for all of the order types.

[bherd-rb]

@davidrpugh Great -- that's much better! I think it is really user-friendly now. I will extend the sandbox as soon as the quote stuff has been merged in. Then we can see if this is sufficient for the release.

[davidrpugh]

@bherd-rb Sounds good. I will try to get to this over the weekend but can't promise anything.

[davidrpugh]

@bherd-rb I have made the necessary changes to the various order traits as discussed above. I have also change the + and - methods on the FourHeapOrderBook class to be insert and remove. This improves the syntax on the Java side.

I don't like that Java users creating a new FourHeapOrderBook instances using...

FourHeapOrderBook<GoogleStock> orderBook1 = FourHeapOrderBook.empty(
                LimitAskOrder$.MODULE$.ordering(),
                LimitBidOrder$.MODULE$.ordering());

...I can sort this problem by creating various Ordering classes (perhaps in their own package) and then place an implicit reference to these classes in the relevant companion objects. Scala users get the nice syntax that makes use of the implicit params; Java users will need to pass the orderings directly, but at least will not have to use the $.MODULE$ syntax.

BTW, do you know why you can directly call the empty method on the FourHeapOrderBook object? It seems like you should need to write FourHeapOrderBook$.MODULE$.empty(???, ???)?

Finally, I would like to figure out a way to avoid the call to the apply method when using the various pricing functions if possible.

[davidrpugh]

@bherd-rb I came across this repo that has a lot of useful information about Java-Scala interop.