The UimaAsynchronousEngine interface has only two sendAndReceive() methods.
There was only one change made to the sendXXX API since UIMA-AS inception.
The
change under discussion here would be the second one.
The sendCAS ( CAS cas, Map options ) has an advantage of keeping the API
simple and extensible but it kinda hides the parameters. The user must
lookup
documentation to discover what options are available and how to use them
sync or async, target or not, etc.
Granted, the UIMA-AS initialize(Map options) uses this style already :)
This new method will create ambiguity since:
sendAndReceiveCAS(CAS cas, List<AnalysisEnginePerformanceMetrics>
componentMetricsList)
and
Map<String, Object> options = new HashMap<String,Object>();
options.put(MODE,SYNCHRONOUS );
options.put(METRICS, new ArrayList<AnalysisEnginePerformanceMetrics>());
sendCAS(cas, options);
are equivalent, and the second one being quite verbose.
What should we say in the documentation? Which style should the user use?
Perhaps we can say that
the new code should use sendCAS(cas, options) since it is more extensible
and ready for future changes
to this API
Jerry
On Tue, Dec 12, 2017 at 2:15 PM, Burn Lewis <burnle...@gmail.com> wrote:
> I would vote against deprecating existing methods.
> I think the issue is do we expect to add more arguments in the future if
> another variant is needed.
> If not then adding 2 new methods is consistent with past extensions ... but
> I do see a 3rd sendAndReceiveCAS method that is not in the Javadocs.
> Alternatively Lou's 1 new method would provide for future extensions. The
> 2nd arg could be a map, just as the initialize method takes a map:
>
> String sendCAS ( CAS cas, Map options )
>
> Burn
>
>
> On Tue, Dec 12, 2017 at 10:33 AM, Marshall Schor <m...@schor.com> wrote:
>
> > Re: 2nd & 3rd proposal, the client would supply an instance of
> > "ProcessingOptions". I assume the user would create this using new
> > ProcessingOptions() and then call the setters it wants. Or perhaps there
> > would
> > be a short-hand positional-arg constructor, as well.
> >
> > Overall, it seems to me that it would be less disruptive to the API
> > stability,
> > and easier for users to learn and use, to just add an overloaded call
> > (proposal
> > #1), and not deprecate anything. I think users would appreciate not
> > having to
> > update older code.
> >
> > -Marshall
> >
> > On 12/11/2017 5:42 PM, Jaroslaw Cwiklik wrote:
> > > Hi, I need to extend UIMA-AS client API as defined by
> > > interface UimaAsynchronousEngine.java
> > >
> > > The new feature I've been working on, should allow a client to send a
> CAS
> > > to a specific instance of a service. Such targeting is optional and
> could
> > > be useful to test if a service is viable (processing can be done).
> > >
> > > To support targeting, a service uses a JMS selector which expects a
> > message
> > > property that uniquely identifies the service. By default, the selector
> > > uses IP:PID as a unique identifier, but a service deployer can define
> a
> > > custom identifier using -D property on the service command line.
> > >
> > > An application client must be able to invoke a UIMA-AS client method
> > which
> > > takes a CAS, unique id of a service to target, and other properties.
> The
> > > targeting is again optional and used for special use cases.
> > >
> > > Current UIMA-AS client uses two styles of calls: asynchronous and
> > > synchronous
> > >
> > > sendCAS(CAS cas) - this is an asynchronous style
> > >
> > > and there are two APIs for synchronous style:
> > >
> > > sendAndReceive(CAS cas)
> > > sendAndReceiveCAS(CAS cas, List<AnalysisEnginePerformanceMetrics>
> > > componentMetricsList)
> > >
> > > To support targeting, I can overload the above creating two new methods
> > >
> > > sendCAS(CAS cas, String serviceTargetId)
> > > sendAndReceiveCAS(CAS cas, List<AnalysisEnginePerformanceMetrics>
> > > componentMetricsList, String serviceTargetId )
> > >
> > > Another suggestion from Lou Degenaro is to create a new method
> > >
> > > submit(CAS cas, ProcessingOptions pos);
> > >
> > > where
> > >
> > > ProcessingOptions() {
> > > void setAsynchronous(); // if this is not called the default is
> > > synchronous
> > > void setMetrics(List<AnalysisEnginePerformanceMetrics> list);
> //null
> > for
> > > asynchronous style
> > > void setTargetInstance(String id); // if not called ,targeting is
> not
> > > done
> > > }
> > >
> > > Burn Lewis commented on this proposal with:
> > >
> > > "Has the advantage of being extendable without having to add another
> send
> > > method.
> > >
> > > Could be a map with a specified set of legal keys but a special class
> is
> > > good too ... especially if had extra constructors, e.g. for a targeted
> > > async request:
> > >
> > > submit ( cas, new ProcessingOptions(true, null, "127.0.0.1:12345") )"
> > >
> > > If submit() is a preferred choice should the sendCAS() and
> > sendAndReceive()
> > > be deprecated to encourage new code to use more flexible API? Or should
> > we
> > > just document that submit() is only
> > > for targeting services?
> > >
> > > Are there any suggestions perhaps which should be considered?
> > >
> > > Jerry
> > >
> >
> >
>
