The JAPI/SAPI are essentially just wrappers around internal things. This is necessary for the Java side of things since some Scala concepts are difficult to represent in Java (e.g. enums) so there's kindof a mapping from scala land to java land. The SAPI mimics the Java API for consistency.
The two are very very very similar, but has a few main differences. The first is making for a Java friendly API. For example, as mentioned earlier, the JAPI includes Java enums for things like ValidationMode and Logging. There are also a couple places where the Java API will return a java.util.List whereas the Scala API will return a scala Seq. The other issue that prevents merging the two is that I found it difficult to create ScalaDoc that would also create JavaDoc. Use use a plugin to convert scaladoc to javadoc, and it works fairly well, but some valid scaladoc just doesn't convert to Javadoc well, so the scaladoc needs to be input different than normal. Also things like example code needs to be in java vs scala, which makes things trickier. - Steve. 02/23/2018 09:32 AM, Mike Beckerle wrote: > Steve, > > At one time there was a issue with the JAPI/SAPI design.... redundant stuff > there, awkward to add things, etc. > In glancing at it the other day it looked unfamiliar to me. Was this fixed, > or is that still outstanding work we need to do? If so we should add comment > to Daffodil-1909 to that effect, or link it to other JIRA tickets about that > issue. > > ...mikeb > > ________________________________ > From: Steve Lawrence <slawre...@apache.org> > Sent: Thursday, February 22, 2018 1:22:00 PM > To: dev@daffodil.apache.org; Mike Beckerle > Subject: Re: more scaladoc needed? > > We do not currently provide the general scaladoc tree for all of > daffodil online anywhere. And I'm hesitant to provide that since I view > anything not in the daffodil-japi or daffodil-sapi subprojects as > internal and subject to change (i.e. not suitable for an API). > > I think DAFFODIL-1909 that you just added is the right approach to solve > this. We should add an abstract class/trait that provides a minimal and > maintainable interface to the internals of the DISimple/DIComplex/etc. > and make that trait available in the japi/sapi so that > InfosetIOutputters can use it. Passing in DISimple/DIComplex/etc. > directly to the InfosetOutputters may have been a mistake, but since > there's really no Java/Scaladoc available for it I don't think we need > to worry about breaking backwards compatibility since no one could > really use this API as is. I suspect this new trait would essentially > have one public method for each of the members in the DFDL Infoset [1]? > > - Steve > > [1] https://daffodil.apache.org/docs/dfdl/#_Toc398030646 > > On 02/22/2018 12:30 PM, Mike Beckerle wrote: >> I was looking at our javadoc and scaladoc for rc2, as linked from here: >> >> >> https://daffodil.apache.org/releases/2.1.0/ >> >> >> My mental experiment was to write my own Java InfosetOutputter (something >> requested by folks at AFRL) to directly output RDF triples from a parse. >> >> >> This turns out to be impossible, as our scaladoc for InfosetOutputter, does >> not allow one to drill into the DISimple, DIComplex or DIArray >> classes/traits of the arguments to the InfosetOutputter method calls. >> >> Do we provide the general scaladoc tree for all of daffodil anywhere online >> other than in a javadoc archive that can be pulled as a managed dependency? >> >> >> >> >> > >
