You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@uima.apache.org by Jaroslaw Cwiklik <cw...@apache.org> on 2017/12/11 22:42:05 UTC
UIMA-AS Client API Change Discussion
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
Re: UIMA-AS Client API Change Discussion
Posted by Lou DeGenaro <lo...@gmail.com>.
No need to deprecate. The legacy signatures can contain stubs that invoke
submit with the corresponding PO.
Lou.
On Tue, Dec 12, 2017 at 10:33 AM, Marshall Schor <ms...@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
> >
>
>
Re: UIMA-AS Client API Change Discussion
Posted by Jaroslaw Cwiklik <cw...@apache.org>.
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 <cw...@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 <bu...@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 <ms...@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
>> > >
>> >
>> >
>>
>
>
Re: UIMA-AS Client API Change Discussion
Posted by Jaroslaw Cwiklik <cw...@apache.org>.
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 <bu...@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 <ms...@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
> > >
> >
> >
>
Re: UIMA-AS Client API Change Discussion
Posted by Burn Lewis <bu...@gmail.com>.
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 <ms...@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
> >
>
>
Re: UIMA-AS Client API Change Discussion
Posted by Marshall Schor <ms...@schor.com>.
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
>