Client running in server context

[ronsigal]

I don't think the relationship between a Client running inside a JAX-RS resource and the server context has ever been clarified. For example, if a provider is discovered by the server container, should it be available to the client? (See #746, for example.) Similarly, if a provider used by a Client running in a resource does @context injection, should it be able to inject all of the injectable types, or just the two (Configuration and Providers) available to the "client side"?

I propose to extend ClientBuilder to make the server context optionally available to a client. In particular, I propose the following two methods:

       /**
        * Determine if Client can access the content of the JAX-RS server
        * side deployment, if it's running in one. Access defaults to true.
        *
        * @param b
        * @return an updated client builder instance
        */
       public abstract ClientBuilder accessServerContext(boolean b);
      
       /**
        * Deactivate a provider
        *
        * @param providerClass class to be deactivated
        * @return an updated client builder instance
        */
       public abstract ClientBuilder disable(Class<?> providerClass);

Suppose three provider classes are registered with the server, C1, C2, and C3, and only the first two are needed. Then do this:

     ClientBuilder.newClient()
        .accessServerContext(true)
        .disable(C3.class);

Here are a couple of use cases.

1. The next MicroProfile REST Client spec version 1.4 (https://projects.eclipse.org/projects/technology.microprofile/releases/rest-client-1.4) proposes that it be possible to inject HttpHeaders into a ClientHeadersFactory object.

2. A client might need access to a security token from a request to propagate it with the client invocation. (Thanks, Bill Burke for that one.)

-Ron

[mkarg]

Thanks for bringing up this topic!

In fact I wonder if it is really needed to configure that, or if it wouldn't be always correct that a client injected into a server always "sees" the server's context? In the end it is used always in reaction upon a server request.

[ronsigal]

Hey @mkarg, yeah, I've always been a bit undecided on the issue, but your alternative also seems reasonable. If nothing else, I think the JAX-RS spec should clarify the subject. I'd be curious to know if anyone sees a use case for allowing a "blood brain barrier" between a Client and it's server context. Maybe it's not a single question. For example, having access to HttpHeaders seems hard to argue against. On the other hand, maybe one would want more control over which providers are available to the Client. Just musing out loud ...

[mkarg]

Yes, thinking more about it, providers seems to be to core issue. In particular, priority of providers. For example, we want JSON be the default of our server, but it needs to talk XML to some backend in turn.

[ronsigal]

Ah, @mkarg, that's a really interesting example. I see three possible solutions:

1. Just work with Accept q values;
2. Introduce a mechanism for altering the priority of providers; or
3. Disable a provider and re-enable it with a different priority.

Maybe 1 is enough. 2 seems a little ... out there. 3 fits in with my proposal. Depending on the number of application providers, you might want to disable all of them (accessServerContext() set to false) and enable a few, or enable all of them (accessServerContext() set to true) and disable a few.

[mkarg]

I think in the end we will need to come up with a solution how to define which part of the original request context to be forwarded into the subsequent client context.

[asoldano]

I think in the end we will need to come up with a solution how to define which part of the original request context to be forwarded into the subsequent client context.

Indeed, this topic needs to be properly and organically treated in the spec.

[ronsigal]

I've written a proposal. It's a work in progress, but it's mostly complete, I think:

The runtime environment of a JAX-RS application is determined by a variety of objects and data from a variety of sources:

1. application scoped

   A. Application
   B. providers
   C. properties

2. request scoped

   A. request URI
   B. headers

When a Client is created inside a JAX-RS server environment, which of those items should be available to the its runtime? I suggest that it should be possible to configure the Client's runtime environment based on the server's environment. Configuration would consist of

1. Determining if the application scoped items are to be inherited from the server environment.

2. Registering or deleting providers.

3. Setting or removing properties.

Some of these are already available in the form of Configurable.register() and Configurable.property(), which are inherited by ClientBuilder. Something like the following should be added to ClientBuilder:

/**
* Determine if Client can inherit the content of the JAX-RS server
* side deployment, if it's running in one. Defaults to true.
*
* @param b
* @return an updated ClientBuilder instance
*/
public abstract ClientBuilder inheritServerContext(boolean b);

/**
* Deactivate a provider
*
* @param providerClass class to be deactivated
* @return an updated ClientBuilder instance
*/
public abstract ClientBuilder disable(Class<?> providerClass);

Note that a property can be removed from the environment by setting it to null.

There are two ways in which the Client environment affects a request execution:

1. It directly affects the execution by the availability of providers.

2. It indirectly affects the execution by way of @context injection into providers.

Of the eight standard @context injectable classes, three are application scoped:

1. Application
2. Providers
3. Configuration

three are request scoped:

1. UriInfo
2. HttpHeaders
3. Request

and two span both:

1. SecurityContext [is that right??]
2. ResourceContext

Of the four @context injectable servlet objects, ServletConfig and ServletContext are application scoped, and HttpServletRequest and HttpServletResponse are request scoped.

It needs to be determined which of these can be injected during a client execution, or, more precisely, which have a value when injected. I can't think of a reason to not make the request scoped information available. Configuring the client environment, then, consists of configuring the information in the application scoped objects.

1. The available providers and the contents of the Configuration can be configured by the existing and new ClientBuilder methods.

2. I'm not sure what to do about Application. Maybe it should just be inherited, since it might contain application specific information, with the warning that getClasses() and getProperties() may not reflect the current state.