Connection Routes

Connection Routes

A Connection Route is referring to an call of an Connection, which is not established, but "bound" to an certain identifier. You may Bound any Connection (which has to be instantiated) to any identifier you like. It still has to be a Class.

Connection routes can be helpful within a handful of situations. You can use this route to override other Connections. Also, a Connection-route might function as an placeholder for any future Connection, that is not yet established or not yet created within the development cycle.

The main advantage of an connection Route is, that you prevent a NullPointerConnection at runtime without having to check every Connection-Key whether or not it is set and without having to establish multiple Connections, just to prevent the previously stated. Also, if you see (at runtime) that your number of Connections are taking to much resources, you can close those Connections and reroute the DefaultConnection to Connections, closed this way.

There are 2 types of Connection Routes.

Type 1: Client#setConnection(Connection, Class);

If you call the Clients setConnection method, using an Connection-Object and an identifier, the Key will route to this certain Connection

This might look like this:

// The client, that this connection-route should be inserted into
Client client = ...
// The custom Connection, which you want to Route.
Connection connection = ...
// The key, under which the Connection should be accessible
Class key = ...

client.setConnection(connection, key);

Or like this, if you want to connect any already established Connection:

// The client, that this connection-route should be inserted into
Client client = ...
// The custom Connection, which you want to Route.
Connection connection = client.getConnection(AlreadyEstablishedConnectionKey.class);
// The key, under which the Connection should be accessible
Class key = ...

client.setConnection(connection, key);

By using this method, you can neither provide null as an Connection or as the key. If you do, you will receive an IllegalArgumentException.

If you want to route a Connection already set inside of this Client, you might as well use the: Client#setConnection(Class, Class); method. This will retrieve the Connection, identified by the first class and route it to the second Class.

By using this method, you can not provide either Class as null. If you do, you will receive an IllegalArgumentException.

Type 2: Client#routeConnection(Connection, Class);

By calling the routeConnection method of the Client-Object, you can create any route you would like. This will still override previously set Connections, identified by the given Class.

The advantage over Client#setConnection(Connection, Class); is, that you might provide null as an identifier. This allows you create a "null-route". A null-route is an elegant way of ensuring to always have an Connection that is used, even if you call: Client#send(Class, Object); with Class = null.

Then, the set null-route will be referred to. So you will send the requested Object over the Connection, routed to null.

The only application of the null-route, that i can think of, is any application, where you don't know the type of Class which this Connection is identified with, at run time.

Creating a Route is possible by stating the following:

// The client, that this connection-route should be inserted into
Client client = ...
// The custom Connection, which you want to Route.
Connection connection = ...
// The key, under which the Connection should be accessible
Class key = ...

client.routeConnection(connection, key);
client.routeConnection(connection, null);

If you want, you can route any existing Connection, by stating the following:

// The client, that this connection-route should be inserted into
Client client = ...
// The key, under which the Connection should be accessible
Class key = ...

client.routeConnection(AlreadyEstablihsedConnection.class, key);
client.routeConnection(AlreadyEstablihsedConnection.class, null);

This will retrieve the Connection, routed to AlreadyEstablihsedConnection.class and route it to the provided new key.

Both method request, that the first argument is not null. If you provide the Connection of the identifier of the already established Connection as null, you will receive an IllegalArgumentException

Considerations:

A route is most likely used as an placeholder. Consider designing your code around that. Creating an large amount of Connection-routes without ever instantiating an Connection is certainly not needed. You might as well ignore Connections all together and just call: Client#send(Object);