For this release I will overload both sendCAS(..) and sendAndReceive(..) to
enable targeting. In the future if there is a need to further extend these
APIs we can revisit the idea of a new method.
-Jerry
On Tue, Dec 12, 2017 at 3:00 PM, Jaroslaw Cwiklik <cwik...@apache.org>
wrote:
> 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
>> > >
>> >
>> >
>>
>
>
