The preferred way to configure the behavior of Portal's WSRP Producer is via the WSRP configuration portlet. Alternatively, it is possible to add an XML file called wsrp-producer-config.xml in the $JBOSS_HOME/standalone/configuration/gatein/wsrp directory. Several aspects can be modified with respects to whether registration is required for consumers to access the Producer's services.
An XML Schema defining which elements are available to configure Consumers via XML can be found in:
$JBOSS_HOME/modules/org/gatein/wsrp/main/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_producer_1_0.xsd
It is important to note that once the XML configuration file for the producer has been read upon the WSRP service first start, the associated information is put under control of JCR (Java Content Repository). Subsequent launches of the WSRP service will use the JCR-stored information and ignore the content of the XML configuration file.
Default configuration
The default producer configuration requires that consumers register with it before providing access to its services but does not require any specific registration properties (apart from what is mandated by the WSRP standard). It does, however, require consumers to be registered before sending them a full service description. This means that our WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. The producer also uses the default RegistrationPolicy paired with the default RegistrationPropertyValidator. We will look into property validators in greater detail later in Registration configuration. Suffice to say for now that this allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not.
GateIn provides a web interface to configure the producer's behavior. You can access it by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. Here's what you should see with the default configuration:
As would be expected, you can specify whether or not the producer will send the full service description to unregistered consumers, and, if it requires registration, which RegistrationPolicy to use (and, if needed, which RegistrationPropertyValidator), along with required registration property description for which consumers must provide acceptable values to successfully register.
We also display the WSDL URLs to access GateIn's WSRP producer either in WSRP 1 or WSRP 2 mode.
Registration configuration
In order to require consumers to register with Portal's producer before interacting with it, you need to configure Portal's behavior with respect to registration. Registration is optional, as are registration properties. The producer can require registration without requiring consumers to pass any registration properties as is the case in the default configuration. Let's configure our producer starting with a blank state:
We will allow unregistered consumers to see the list of offered portlets so we leave the first checkbox ("Access to full service description requires consumers to be registered.") unchecked. We will, however, specify that consumers will need to be registered to be able to interact with our producer. Check the second checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer registrations."). The screen should now refresh and display:
Dropdown menus display available implementations of RegistrationPolicy and RegistrationPropertyValidator. We will keep the default value for now as we will examine these concepts in more details in Customization of Registration handling behavior for more details. Let's add, however, a registration property called email. Click "Add property" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to figure out its purpose:
Press "Save" to record your modifications.
At this time, only String (xsd:string) properties are supported. If your application requires more complex properties, please let us know.
If consumers are already registered with the producer, modifying the configuration of required registration information will trigger the invalidation of held registrations, requiring consumers to modify their registration before being able to access the producer again. We saw the consumer side of that process in the Registration modification on producer error section of the Consumers maintenance chapter.
Customization of Registration handling behavior
Registration handling behavior can be customized by users to suit their Producer needs. This is accomplished by providing an implementation of the RegistrationPolicy interface. This interface defines methods that are called by Portal's Registration service so that decisions can be made appropriately. A default registration policy that provides basic behavior is provided and should be enough for most user needs.
While the default registration policy provides default behavior for most registration-related aspects, there is still one aspect that requires configuration when using this default registration policy: whether a given value for a registration property is acceptable by the WSRP Producer. This is accomplished by plugging a RegistrationPropertyValidator in the default registration policy. This allows users to define their own validation mechanism of registration properties that consumer pass to the producer.
Please refer to the Javadoc for org.gatein.registration.RegistrationPolicy and org.gatein.registration.policies.RegistrationPropertyValidator for more details on what is expected of each method.
Defining a registration policy is required for the producer to be correctly configured. If you don't provide one, the DefaultRegistrationPolicy associated to the DefaultRegistrationPropertyBehavior will be used:
GateIn Portal can automatically detect deployed implementations of RegistrationPolicy and RegistrationPropertyValidator, assuming they conform to the following rules:
-
The implementations must follow the Java ServiceLoader architecture. In essence, they must be packaged as JARs and contain a special META-INF/services/org.gatein.registration.RegistrationPolicy file for RegistrationPolicy implementations or META-INF/services/org.gatein.registration.policies.RegistrationPropertyValidator for RegistrationPropertyValidator implementations containing a line with the fully qualified name of the implementation class. Note that you should be able to package several implementations in the same JAR file, provided that each implementation class is referenced on its own line in the appropriate service definition file. To make things easier, we provide an example project of a RegistrationPolicy implementation and packaging at https://github.com/gatein/gatein-wsrp/tree/master/examples/policy.
-
The implementation classes must provide a default, no-argument constructor for dynamic instantiation.
-
The implementation JARs must be deployed in $JBOSS_HOME/gatein/extensions.
-
The implementation JARs should use the .wsrp.jar extension. This is not mandatory but helps process the file faster by marking it as a WSRP extension.
If you have deployed the example RegistrationPolicy that we provide as detailed above, registration-policy-example.wsrp.jar in $JBOSS_HOME/gatein/extensions, it should appear in the list of available policies in the producer configuration screen as follows:
WSRP validation mode
The lack of conformance kit and the wording of the WSRP specification leaves room for differing interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when using consumers from different vendors. We have experienced such issues and have introduced a way to relax the validation that our WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. Note that we only relax our validation algorithm on aspects of the specification that are deemed harmless such as invalid language codes.
By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you might want to try to relax the validation mode. This is accomplished by unchecking the "Use strict WSRP compliance." checkbox on the Producer configuration screen.