[wildfly-dev] IMPORTANT: First overview of changes to jboss-ejb-client 3.0 for WildFly 10 (probably)

[David M. Lloyd]

I don't want to commit this to a specific WildFly release but I guess 
and hope it'll come in around WildFly 10 or so (definitely not 9).

As previously discussed, the EJB client architecture is undergoing the 
following substantial changes:

• Introduction of URIAffinity, and URI-based invocation
• Expansion of the 'ejb' JNDI initial context to auto-associate the 
PROVIDER_URL as the URI affinity for looked-up proxies
• Elimination of all "nested" EJB client context functionality
• Integration with Elytron for client identity management
• Deferral to Remoting for automatic connection management
• Unification of client configuration, so the Elytron authentication 
client, Remoting connection management, remote transaction client, and 
EJB client configurations all can be configured in one file or 
deployment descriptor

As such, I've introduced a 2.x branch for upstream where continued 
development of the 2.x series will take place.  The "master" branch is 
being re-purposed towards this new development, targeted for 3.x of this 
library.

There are a number of compatibility considerations from 2.x to 3.x. 
Most (I hope) existing client code (which avoids specialized manual 
configuration or nested client contexts) should continue to function 
as-is, with the following exceptions:

• The following classes and interfaces are currently removed in my 
working copy:
    • ClusterContext - replaced with discovery (?)
    • ClusterNodeManager - replaced with discovery

    • ClusterNodeSelector - replaced with discovery
    • DeploymentNodeSelector - replaced with discovery

    • ContextSelector - replaced with general selector class
    • ConstantContextSelector
    • IdentityEJBClientContextSelector
    • ThreadLocalContextSelector

    • EJBClientContextInitializer - no replacement
    • DefaultInterceptorsClientContextInitializer
    • TransactionRecoveryContextInitializer

    • EJBClientContextIdentifier - no replacement
    • NamedEJBClientContextIdentifier

    • DefaultCallbackHandler - no replacement

    • EJBClientConfiguration - replaced with context builder
    • PropertiesBasedEJBClientConfiguration

    • EJBClientContextListener - no replacement
    • EJBClientInterceptor.Registration - no replacement (interceptor 
set cannot be changed)
    • EJBClient*TransactionContext - replaced by 
wildfly-transaction-client facility
    • EJBReceiverContext - no replacement
    • ReceiverInterceptor - no replacement (internal class)

    • ALL public classes in the org.jboss.ejb.client.remoting package 
including ReconnectHandler

• The following changes will be made to these core classes and interfaces:
    • EJBClient
       • Added more createSession() variants to support new affinity types
       • Change createSession() methods to throw CreateException instead 
of Exception
       • Remove createProxy() and createSession() variants which accept 
EJBClientContextIdentifier
       • Remove getEJBClientContextIdentifierFor() method
    • Attachable
       • Remove getAttachments() method
    • EJBClientContext
       • No longer implements Closeable
       • Remove close() method
       • Remove all static create() methods, replaced with Builder class
       • Remove finalize() method
       • Remove getClusterContext(), getEJBClientConfiguration(), 
getOrCreateClusterContext(), removeCluster()
       • Remove selector-related methods, replaced with general Selector 
class
       • Remove register*() and unregister*() methods (providers are 
added to Builder)
       • Remove require() method which accepts EJBClientContextIdentifier
       • Add getInvocationTimeout() method
    • Affinity
       • Add forUri() factory method
    • EJBClientInvocationContext
       • Add getCompressionLevel(), isClientAsync(), and isIdempotent() 
query methods
       • Remove finalize()
    • EJB*Locator classes
       • Additional constructors which also accept an affinity
       • Additional "copy" constructors which accept a locator and 
affinity, to change the target affinity
    • EJBReceiver class
       • openSession() method changed to accept a stateless EJB locator
       • Constructor changed to no args
       • Remove all send*() and other methods related to transactions
       • Remove associate(), getNodeName(), [de]registerModule(), exists()
    • EJBReceiverInvocationContext
       • Remove retryInvocation() method
       • Remove getEjbReceiverContext() method
       • Remove getNodeName() method
    • EJBMetaDataImpl
       • Deprecated, changed to not use raw types
    • RequestSendFailedException
       • Replaced constructor with standard exception four-constructor setup
• The following API classes are added:
    • EJBClientPermission - a general permission class
    • AbstractEJBMetaData - type-safe hierarchical version of 
EJBMetaDataImpl
    • EJBClientContext.Builder - forwards-compatible builder for 
EJBClientContext
    • EJBDiscoveryProvider - an interface to provide pluggable discovery
    • EJBTransportProvider - an interface to provide URI-compatible 
transport (factory for EJBReceivers)
    • URIAffinity - a type of affinity which has a URI for a target

Note in particular that most of the cluster-support infrastructure is 
presently removed with no replacement.  It is my hope and intent that 
the discovery infrastructure will be able to take over this function. 
How much of the code will be new, compared to how much of the code can 
be forward-ported and reintroduced from 2.x, remains to be discussed.

At present, the plan is for wire compatibility to be supported for 2.x 
clients talking to 3.x servers and vice-versa.

Transaction handling will be relegated to a separate 
wildfly-transaction-client API.  However the getUserTransaction(node) 
method will continue to be supported as a deprecated delegation to the 
transaction-client API.  In addition, when talking to a 2.x server, it 
is expected that a wildfly-transaction-client SPI implementation will 
piggyback on the existing EJB protocol transaction messages.

If any of these API changes seems unacceptable, now is the time to 
discuss it.  All the code that was removed was determined to be tied too 
tightly to the previous location or configuration strategy, and thus 
couldn't sensibly be supported going forward.  I have hopefully been 
adequately upfront about what I intended to remove or support going 
forward.  In addition, by supporting the 2.x client, most migration 
concerns can hopefully be mitigated.  But it's possible that some 
classes or methods could indeed be reintroduced with sensible semantics 
and in such a way as to not cause problems; if you have any thoughts 
along these lines, please share them and we can discuss them on a 
case-by-case basis.

I've pushed up the proposed baseline 3.0 API at 
https://github.com/dmlloyd/jboss-ejb-client/tree/uri_invocation for 
review.  I intend for pull requests that are relevant to both old and 
new code bases to be applied to both if possible, to avoid increasing 
the incompatibility window even further.

-- 
- DML