Chapter 34. Configuring the WSRP Producer
The preferred way to configure the behavior of the portal's WSRP Producer is through the WSRP configuration portlet. Alternatively, it is possible to add an XML file called
wsrp-producer-config.xml in the JPP_HOME/standalone/configuration/gatein/wsrp directory. Several aspects can be modified with respect to whether registration is required for consumers to access the Producer's services.
Important
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 the 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.
Note
An XML Schema defining which elements are available to configure Consumers via XML can be found in
JPP_HOME/modules/org/gatein/wsrp/main/wsrp-integration-api-2.2.2.Final.jar/xsd/gatein_wsrp_producer_1_0.xsd
34.1. Default Producer Configuration
The default producer configuration requires that consumers register with it before providing access 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 the 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. This allows users to customize how the Portal's WSRP Producer determines whether a given registration property is valid or not.
The portal provides a web interface to configure the producer's behavior. It is accessed by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. The image below is what you should see with the default configuration:
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.
The WSDL URLs to access the Portal's WSRP producer are displayed either in WSRP 1 or WSRP 2 mode.
34.2. 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.
To configure the producer starting with a blank state:
You will allow unregistered consumers to see the list of offered portlets so you leave the first checkbox ("Access to full service description requires consumers to be registered.") unchecked. You will, however, specify that consumers will need to be registered to be able to interact with the producer. Check the second checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer registrations."). The screen should now refresh and display:
You can specify the fully-qualified name for your
RegistrationPolicy and RegistrationPropertyValidator there. Keep the default value.
Add 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:
Click "Save" to record the modifications.
Note
At this time, only String (xsd:string) properties are supported. If your application requires more complex properties, please supply feedback.
Note
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.
34.2.1. 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: 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 for registration properties that are passed by a consumer to a producer.
See the Javadoc™ for https://github.com/gatein/gatein-wsrp/blob/master/producer/src/main/java/org/gatein/registration/RegistrationPolicy.java and https://github.com/gatein/gatein-wsrp/blob/master/producer/src/main/java/org/gatein/registration/policies/RegistrationPropertyValidator.java 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 is used.
The 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:
- They must be packaged as JARs
- For
RegistrationPolicyimplementations, they must contain a specialMETA-INF/services/org.gatein.registration.RegistrationPolicyfile. - For
RegistrationPropertyValidatorimplementations they must containMETA-INF/services/org.gatein.registration.policies.RegistrationPropertyValidatorand include a line with the fully qualified name of the implementation class.
Note
It is possible 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
JPP_HOME/gatein/extensions. - The implementation JARs should use the
.wsrp.jarextension. This is not mandatory but helps process the file faster by marking it as a WSRP extension.
If you deployed the example
RegistrationPolicy provided from the github repository (registration-policy-example.wsrp.jar) to the JPP_HOME/gatein/extensions directory, it will appear in the list of available policies in the producer configuration screen.
34.3. 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.
A way to relax the validation that the WSRP producer performs on the data provided by consumers has been introduced to help with interoperability by accepting data that would normally be invalid. Note that this validation algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes.
By default, the WSRP producer is configured in strict mode. In case of issues with a given consumer, you can skip the validation mode. To skip validation, clear the "Use strict WSRP compliance." check box on the Producer configuration screen.