This sample explains how to use the Governance API of WSO2 Governance Registry to create a simple webservice which is capable of looking up service endpoints. WSO2 Governance Registry contains an Apache Axis2 based runtime as a part of the WSO2 Carbon Framework. You can deploy web services on this runtime, which can be used as internal endpoints to receive notifications generated on the WSO2 Governance Registry. We will be reusing the code of the Handler Sample in this example. This sample requires Apache Maven. See Installation Prerequisites for links on how to install it. This example also explains how to use soapUI, which is a very useful tool for testing web services.
Instructions
1. Navigate to GREG_HOME/samples/handler/src to find the source code of the Handler Sample.
2. Add the following dependency to your POM file. Make sure you update the current version of carbon governance (e.g. 4.5.1).
Project Object Model (POM) is an XML representation of a Maven project held in a file named pom.xml which can be found in the GREG_HOME/ samples/handler/src directory.
<dependency>
<groupId>org.wso2.carbon.governance</groupId>
<artifactId>org.wso2.carbon.governance.api</artifactId>
<version>{current version of the carbon.governance}</version>
</dependency>
3. Add the following plugin to your POM file:
<plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-scr-plugin</artifactId> <version>1.7.2</version> <executions> <execution> <id>generate-scr-scrdescriptor</id> <goals> <goal>scr</goal> </goals> </execution> </executions> </plugin>
4. Comment-out the following in your POM file:
<!--Fragment-Host>org.wso2.carbon.registry.core</Fragment-Host-->
The Fragment-Host Bundle Manifest Header declares this sample bundle to be a Fragment of the Registry Kernel. This would mean that the sample handler bundle will become an extension to the Registry Kernel. However, bundles containing services.xml files would not be deployed until the Apache Axis2 runtime has been initialized. Due to OSGi bundle start-up order, it is required that the Registry Kernel starts up before the Apache Axis2 runtime.
Since the Fragment now also being an extension to the Registry Kernel, the combination of this bundle and the Registry Kernel (plus any other fragments) should start up before the Apache Axis2 runtime. But, due to the bundle not getting deployed until the Apache Axis2 runtime has been initialized, it will create a deadlock situation. Due to this reason, we have to get rid of the Fragment-Host header.
5. Create a file named services.xml in GREG_HOME/samples/handler/src/resources/META-INF and add the following content:
<serviceGroup>
<service name="EndpointLookupService" scope="transportsession">
<transports>
<transport>http</transport>
</transports>
<parameter name="ServiceClass" locked="false">
org.wso2.carbon.registry.samples.services.EndpointLookupService
</parameter>
</service>
</serviceGroup>
6. Add a new Java Class named EndpointLookupServiceComponent at
GREG_HOME/samples/handler/src/src/main/java/org/wso2/carbon/registry/samples/services/EndpointLookupServiceComponent.java with the following source:
package org.wso2.carbon.registry.samples.services;
import org.wso2.carbon.registry.core.service.RegistryService;
/**
* @scr.component name="org.wso2.carbon.registry.samples.endpoint.lookup" immediate="true"
* @scr.reference name="registryService.service"
* interface="org.wso2.carbon.registry.core.service.RegistryService"
* cardinality="1..1" policy="dynamic" bind="setRegistryService" unbind="unsetRegistryService"
*/
public class EndpointLookupServiceComponent {
private static RegistryService registryService;
protected void setRegistryService(RegistryService registryService) {
EndpointLookupServiceComponent.registryService = registryService;
}
protected void unsetRegistryService(RegistryService registryService) {
EndpointLookupServiceComponent.registryService = null;
}
public static RegistryService getRegistryService() {
return registryService;
}
}
See also Declarative Services and Apache Maven SCR Plugin.
7. Add another new Java Class named EndpointLookupService at
GREG_HOME/samples/handler/src/src/main/java/org/wso2/carbon/registry/samples/services/EndpointLookupService.java with the following source:
package org.wso2.carbon.registry.samples.services;
import org.wso2.carbon.governance.api.exception.GovernanceException;
import org.wso2.carbon.governance.api.generic.GenericArtifactFilter;
import org.wso2.carbon.governance.api.generic.dataobjects.GenericArtifact;
import org.wso2.carbon.governance.api.generic.GenericArtifactManager;
import org.wso2.carbon.registry.core.Registry;
import org.wso2.carbon.registry.core.exceptions.RegistryException;
import java.util.LinkedList;
import java.util.List;
/**
* This is the class used to implement the endpoint lookup service.
*/
public class EndpointLookupService {
private Registry governanceRegistry;
public EndpointLookupService() {
try {
governanceRegistry = EndpointLookupServiceComponent.getRegistryService()
.getGovernanceSystemRegistry();
} catch (RegistryException e) {
e.printStackTrace();
}
}
/**
*
* @param serviceName name of the service
* @param serviceNamespace name space of the servic
* @param version service version
* @param environment service endpoint environment
* @return endpoints satisfies the given criteria
* @throws GovernanceException
* @throws RegistryException
*/
public String[] getEndpoints(final String serviceName, final String serviceNamespace,
final String version, final String environment)
throws GovernanceException, RegistryException {
GenericArtifactManager manager=new GenericArtifactManager(governanceRegistry,"service");
GenericArtifact[] artifacts = manager.findGenericArtifacts(new GenericArtifactFilter() {
@Override
public boolean matches(GenericArtifact genericArtifact) throws GovernanceException {
return serviceName.equals(genericArtifact.getQName().getLocalPart()) &&
(serviceNamespace == null || serviceNamespace.length() == 0 ||
serviceNamespace.equals(genericArtifact.getQName().getNamespaceURI())) &&
(version == null || version.length() == 0 ||
version.equals(genericArtifact.getAttribute("overview_version")));
}
});
if (artifacts != null && artifacts.length > 0) {
List<String> endpoints = new LinkedList<String>();
for (GenericArtifact artifact : artifacts) {
String[] entries = artifact.getAttributes("endpoints_entry");
if (entries != null && entries.length > 0) {
for (String entry : entries) {
int idx = entry.indexOf(":");
if (entry.substring(0, idx).equals(environment)) {
endpoints.add(entry.substring(idx + 1));
}
}
}
}
return endpoints.toArray(new String[endpoints.size()]);
}
return new String[0];
}
}
8. Compile the source code by running the following command inside GREG_HOME/ samples/handler/src:
mvn clean install
The command mvn clean install will trigger an Apache Maven Build in your command line. This requires you having installed Apache Maven. See Installation Prerequisites for links on how to install it.
A successful run of Apache Maven will generate a report similar to the following:
9. Copy the GREG_HOME/ samples/handler/src/target/org.wso2.carbon.registry.samples.handler-4.6.0.jar into GREG_HOME/repository/components/dropins.
10. Start the server and observe the command prompt. See Running the Product for more information.
Running the Sample
1. After the sample has been successfully deployed and the server has started, open a browser Window and type the following URL:
http://localhost:9763/services/EndpointLookupService/getEndpoints?serviceName=SimpleStockQuoteService&environment=Dev
In this step, we only have passed in the parameters serviceName and environment. This sample service also supports serviceNamespace and version as optional parameters.
2. This should produce an output similar to the following:
<ns:getEndpointsResponse xmlns:ns="http://services.samples.registry.carbon.wso2.org"
xmlns:ax2549="http://exception.api.governance.carbon.wso2.org/xsd"
xmlns:ax2551="http://api.registry.carbon.wso2.org/xsd"
xmlns:ax2550="http://exceptions.core.registry.carbon.wso2.org/xsd">
<ns:return>http://localhost:8280/SimpleStockQuoteService</ns:return>
<ns:return>https://localhost:8243/SimpleStockQuoteService</ns:return>
</ns:getEndpointsResponse>
Web Services hosted on an Apache Axis2 runtime can be invoked both via REST as well as SOAP. In the steps above, we have made a REST invocation using a Web Browser. You can invoke the same service using SOAP. To see the WSDL for this service, open the following URL on a web browser.
http://localhost:9763/services/EndpointLookupService?wsdl
Follow the steps below to learn how to invoke this sample through SOAP using soapUI.
1. Create a new project using soapUI.
2. Simply copy the WSDL URL in the New soapUI Project dialog box. Use the following URL:
http://localhost:9763/services/EndpointLookupService?wsdl
Press the "OK" button to create the project. Make sure to keep the Create Requests option selected.
3. Expand the getEndpoints operations and right-click the auto-generated request to display the request editor.
4. Fill in the following payload as the request. At least one endpoint must exist for the Dev environment in order to receive a response.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://services.samples.registry.carbon.wso2.org">
<soap:Header/>
<soap:Body>
<ser:getEndpoints>
<ser:serviceName>SimpleStockQuoteService</ser:serviceName>
<ser:environment>Dev</ser:environment>
</ser:getEndpoints>
</soap:Body>
</soap:Envelope>
5. Click the submit button to make the request to WSO2 Governance Registry.
6. Obtain the response from the server.
