[Jakarta RESTful Web Services] Provide a configurable client

[maho7791]

As the REST resources are configurable with extension in the specification on the server side, it would be great to have a similar mechanism, that makes the client configurable.
In fact we already have the ClientBuilder service. I see it similary like an application, so we could also bind extensions (maybe with restrictions) to a ClientBuilder service instance with a given name.
An example could be registering MessageBodyReader/Writer to a client.

Regarding spec section: 151.8.1, I would like to discuss it again. At least I would like to open the spec in a way, that this way of configuration might be possible, whereas there must me a default "ClientBuilder", like out default application.

[juergen-albert]

I'd suggest the following:

Clients can be configured individually with some properties to define the desired preconfigured extensions. In order to avoid specifying a PID for the Client, which would make only one implementation possible, we also need to specify a mechanism for a client implementation to announce its configuration PID. As @timothyjward suggested, we can use the default Client we register to announce the PID to use.

[timothyjward]

As @timothyjward suggested, we can use the default Client we register to announce the PID to use.

Proposal:

The ClientBuilder service registers the service property osgi.jakartars.client.factorypid which is a factory PID that can be used with the following configuration:

name - String required, set as the osgi.jakartars.client.name (avoid osgi.jakartars.name to reduce confusion with whiteboard filters) service property on the registered service
extension.filters - String+ optional, defines a list of extension selection filters that must be satisfied for the client

When the configuration exists and every filter in the filter list is satisfied a Client service is registered with all of the selected extensions applied.

We would need to add a new ClientRuntimeDto containing an array of ClientDto and FailedClientDto. This could be made available through the JakartarsServiceRuntime service, but we may prefer to create a JakartarsClientRuntime service to allow the implementation to be split more easily into client and server portions.

Open questions:

• what if more than one extension service matches a particular filter? Do all get registered or just the highest rank
• what if the same extension service matches more than one filter? Does this count as both filters being satisfied?

[maho7791]

Hi Tim,
I like this proposal and would Prefer having the JakartarsClientRuntime. This would make it easier to have just use the client part without having a server implementation part as dependency, which is then just a packaging thing. It would also separate the to views client and server in an explicit way.

Regarding you question I think, it is described in
https://jakarta.ee/specifications/restful-ws/3.1/jakarta-restful-ws-spec-3.1.html#priorities

It says:

*"Note that even though, as explained in Binding in Client API, annotations are not used for binding in the Client API, they are still used to define priorities. Therefore, if a priority other than the default is required, the @priority annotation must be used for a filter or interceptor registered with the Client API.

The order in which filters and interceptors that belong to the same priority class are executed is implementation dependent."*

The jakarta.ws.rs.core.Configurable allows the registration with a priority. A Client is a Configurable.

To get a proper priority, I think we could sort

• by @priority, if none or same
• by service rank, if none or same
• by service id where a lower service id has higher priority, because it is an older service (like OSGi does it e,g, in the wiring, where older wirings have priority)

When same extension service matches multiple filters, the from my perspective it fullfilled the pre-defined requirements for this Client. So, in the end the extension would be registered only once to the Client.

For me it seems your proposal would lead to a state, where a can client only registered, if all extension filter conditions are fulfilled. We would get a set of extension services, that needs to be ordered correctly and registered to the client.

[timothyjward]

We should use the same rules as defined in https://docs.osgi.org/specification/osgi.cmpn/8.0.0/service.jaxrs.html#d0e134480 (which unsurprisingly match what you've just described). Referring to that section of the specification will eliminate the risk that we end up with more than one ordering.

We will need to update the extensions section to:

1. List ClientRequestFilter, ClientResponseFilter and RxInvokerProvider as valid extension types
2. include the overall ordering for client requests,
3. Point out that ContainerRequestFilter and ContainerResponseFilter and NameBinding are only valid for the server and not valid for clients
4. also to point out that ClientRequestFilter, ClientResponseFilter and RxInvokerProvider extensions are only valid for clients and not valid for the server.

[maho7791]

Agree!

And we have to define the JakartarsClientRuntime with its ClientDTO and FailedClientDTO as well the structure for the ExtensionDTO and FailedExtensionDTO.

When do we start ;-)

[timothyjward]

When do we start ;-)

You have the pen on the 2.1 update ;)

Are you also able to look at the Jakarta REST 4.0 release goals and check whether there is anything coming which will be breaking for us?

[maho7791]

Here is a presentation:
https://github.com/spericas/jaxrs-api/blob/release-4.0/JakartaRest40.pdf

• CDI will be deeper integrated into REST 4, especially @Inject annotation usage :-(

• Jersey/HK2 might handle that for us, like today. I hope there will be no need to depend on an CDI implementation. It seems it is more about using CDI injection annotations and scopes instead of own ones.

• They may want to integrate Jakarta Concurrency

[maho7791]

You have the pen on the 2.1 update ;)

Oki, do I get an own branch?

[timothyjward]

The correct branch name would be design/607

• design - because this is spec design/update work not requirements gathering
• 607 - because that is the id of the issue which started the design work (i.e. this issue)