Introduction

This guide will describe the interfaces available for extending JParam.

Extension Points

There are four extension points available in JParam not all must be used in order to achieve requiered funtionality, one can extend only specific points.

In general, most of the features available in XParam are also available in JParam (with one major exception which is templates and typed collection that are not available in Java). This guide is still a preliminary release and doesn't include all use cases and usage samples of the more elaborate and complete XParam guide, if needed it can be referenced to have a better understanding of the entire concept.

The one major difference between JParam and XParam API is the registration interface, in XParam it is based on C++ macros and template instansiations while in Java it is based on reflection using helper classes, it is quite probably that the registration interface of XParam will have very little relevance to JParam if any.

  1. How to add support for new Classes/JParam types
  2. How to let JParam know how to convert new classes, or add new conversion schemes to existing classes
  3. How to add new constants to the JParam syntax
  4. Some extension related issues that were not yet implemented

Classes/Types

Java classes and JParam types must be registered in order to take part in the JParam syntax, both for parsing from JParam strings and for serializing from Java objects.

Basically this is a simple mapping from a Java Class to a JParam Type Name.

For instance the Java Class ArrayList is mapped to the JParam type named vector. Due to platform compatibility issues, it might occur that a several JParam types will be mapped to a single Java Class (for example JParam types int and long are bothed mapped to Java Class Long and vice versa.

Once a Java class is registered to a JParam type name, it is scanned for its constructors, and a creation scheme is defined for each public constructor using the constructor argument.

When a constructor with a single argument is detected, it is also considered as a user converter (see XParam convertion guide for more information on subject). Unlike XParam there is no way to define a construcor as explicit (meaning that it will not be used as a converter).

It is also possible to register a helper class whos method are then scanned for complient creation methods.

Method validation rules are as follows:

  • The method must be public
  • The method must be static
  • The method name must start with "create"
  • The method name must return a non-void and non-primitive type

The TypeNameRegistry JavaDoc contains explanations regarding the registration interface itself.

The CreatorRegistry JavaDoc contains explanations regarding the registration interface itself for creator and helper classes.

Conversions

JParam can be extended by registering conversions, by doing this JParam can try to convert object to other types in two occasions, one is the destination type matching when used in Parameter type binding, the second is the best creator detection that will be performed by checking all possible conversions and choosing the best one according to C++ method invocation resolution.

Conversion patterns can be concatenated and actually JParam concatenates all compatible conversions in registration time, this way JParam can have a full set of possible conversions along with their conversion weight for fast lookup when object creation or destination type matching is needed, the best converter (if one exists and is not ambigous) is used.

There are two means of registering a converter, one by implementing the IConverter interface (or by subclassing AbstractConverter) the second option is to use a helper class.

When a helper class is registered, all of its methods are scanned, and the methods that are considered as valid converters are then registered as user converters.

Method validation rules are as follows:

  • The method must be public
  • The method must be static
  • The method name must be one of:
    1. create/user_create - for User conversion
    2. promote_create - for Promotion conversion
    3. std_create - standard create
  • The method name must return a non-void type

The ConverterRegistry JavaDoc contains explanations regarding the registration interface itself

Constants

The last and most simple extension point is the constant definition. Constant are string literals that are sabstituted during parsing into typed Java values, examples of such constants are:

  1. true - Boolean.TRUE
  2. false - Boolean.FALSE
  3. NULL - null

As allway there are two way of registering these constants, one is via static final fields in a helper class and the other is direct registration through the ConstantRegistry JavaDoc

Future work

  • There are several things missing in JParam with regards to extension, the first and most important one is the one of typed collections. In JDK1.5 where generics are introduced to the language, it is possible that JParam could also leverage this funcionality to support simplistic templates as in C++. Regardless of this, typed arrays should also be supported.
  • Another aspect that is missing is more control over what is registered and what it triggers, currently there is no way to define a constructor that will not become a converter, due to this limitation for instance, JParam can convert a float to a Map since a map has a constructor from int which defines its initial capacity, and float has a standard conversion to an int.
  • One more issue that needs to be addresses is the ability to define via configuration the primitive mapping of types, if cross-language interoperability is needed, the definition of primitive types might differ between two implementations.
  • Due to the server-side nature of the Java language, it is quite possible that JParam will be used as an adapter to a server, in this case it is quite probable that in time there might be several interfaces externalized by the same server, due to the current singleton implementation of JParam, it is impossible (or at least very hard) to instantiate several instances that might behave differently.
  • One thing that is missing from JParam (and XParam) is the ability to define "tentative string representation" that is I would like to have a typed object instantiated from an untyped string, for instance I would like to have the string "192.168.1.1" translated to an IP class rather than a string. But I wouldn't want on the other hand to have JParam try and convert "192.a.b.1" to and IP, it should know that this is not a valid conversion and should choose another conversion over it.