Previous
Next


The Admin Service  Locate

Overview  Locate

The Admin Service, the core System Web service, allows you to manage advanced settings for each Web service deployed on a WSO2 SOA Enablement Server. Using this Web service, it is possible to manage settings like security mechanisms, transport interceptors, polymorphism, automatic Web service authentication, and automatic authorization checks per Web Service method. This service consists of four parts, each with its own interface:

The Admin Service SOAP endpoint is accessible at http://localhost:6060/mgmt/adminservice (assuming that WSO2 SOA Enablement Server is running on localhost and the default port).

[Note]Note

If the WSO2 SOA Enablement Server is running in secure mode, then this service is protected both by authentication and authorization.

If an error occurs when using the Admin Service, an org.systinet.wasp.admin.AdminServiceException is thrown.

Web Services Administration  Locate

The getServiceInstances() interface of the Admin Service provides management of deployed services.

The following is a brief overview of the Admin Service methods for Web service Administration.

Note that if the WSO2 SOA Enablement Server is running in secure mode, the methods provided by this interface are protected by authorization.

For further details on Admin Service, check either the ServiceAdministration API or its WSDL.

Admin Service Methods for Web Services Monitoring  Locate

The Service Monitoring interface is used to help you with Web service debugging, performance, and message metering. It contains the following methods:

  • debugControl(org.systinet.wasp.admin.ServiceEndpoint, int)

    WSO2 SOA Enablement Server provides support for tracing incoming and outgoing SOAP messages to and from a Web service. You can turn this support on or off for each service endpoint. The debugControl() method allows you to control tracing Web service communication; it is possible to enable or disable tracing in addition to get and clean the log using this method.

    The tracing log is shared by Web services that come from the same package. Once a Web service's message tracing is enabled, the log is stored in a file named debug.txt in the package root directory. The log may be accessed directly, using this method, from the administration console or by accessing the service endpoint by pointing a web browser to http://yourhost:yourport/waspcontext/yourservice?debug.

  • dataThroughputControl(org.systinet.wasp.admin.ServiceEndpoint, int)

    Using this method, you can control the monitor for service endpoint data throughput. The monitoring log holding information such as total in/out throughput, last request in/out throughput, average per request in/out throughput, number of hits for a service endpoint, is obtained using this method.

    [Note]Note

    Changes made using this method to the service endpoint interceptor chain are transient. To make the use of the message size interceptor permanent, you must store the interceptor chain for the service endpoint using the interceptorControl() method.

    [Note]Note

    The monitoring log is not persistently stored. It is lost on server reboot.

  • performanceControl(serviceEndpoint, controlOperation)

    Manages the service endpoint performance monitor. Using this method, the monitoring log that contains the fastest, slowest, average, last request and total dispatch time in addition to the number of requests can be obtained.

    [Note]Note

    Changes made using this method to the service endpoint interceptor chain are transient. To make the use of the message size interceptor permanent, you must store the interceptor chain for the service endpoint using the interceptorControl() method.

    [Note]Note

    The monitoring log is not persistently stored. It is lost on server reboot.

If the WSO2 SOA Enablement Server is running in secure mode, then methods provided by this interface are protected by authorization.

For further details please check either the Service Monitoring API or its WSDL.

Server Preferences  Locate

Server preferences refer to the configuration state of server-side components, such as security providers and transport settings. AdminService provides remote access over SOAP to set and get particular server preferences in a persistent manner. The WSO2 SOA Enablement Server Configuration API ensures the durability of these preferences.

Server preferences do not have a base type in common. They are independent of each other. On the server, they are stored in DOM. The DOM is also used between server and client communication. This means the client can access the server preference the same way as the server can. The difference is that the full details of DOM access are often hidden from the client. For example, in the case of commonly used preferences (such as TransportHTTPServer), the WSO2 SOA Enablement Server Java client can acquire a Java Proxy instance that wraps the DOM, making its data accessible as Java objects.

Levels of API to access Server Preferences  Locate

There are two levels of API to access Server Preferences:

The ServerPreferences API provides three methods as a part of the AdminService interface:

The Helper Java class API provides the following public static methods for WSO2 SOA Enablement Server Java client:

  • getPreferenceMetadataByName(AdminService adminService, String name) returns preference's metadata of given name.

  • getPreferenceByName(AdminService adminService, String name) returns preference's DOM of given name.

  • getPreferenceBeanByName(AdminService adminService, String name) returns preference's Proxy bean of given name.

  • setPreferences(AdminService adminService, Object bean) uses association created in DOM2Bean between Proxy object and DOM and meta to set preference on AdminService.

  • Object DOM2Bean(org.w3c.dom.Element dom, PrefsMetadata meta)creates Java Proxy object on DOM with type stored in meta. Proxy is associated with dom and meta for PreferencesHelper.setPreferences() method.

  • org.w3c.dom.Element.getBeanDOM(Object bean) returns associated DOM with proxy bean.

  • PrefsMetadata getBeanMetadata(Object bean) returns associated metadata with proxy bean.

  • addItem2array(Object[] array, Object newItem)

    creates bigger array containing items of provided array plus newItem (in the last position).

Available Preferences  Locate

AdminService maintains a list of all available preferences that a client can access. The client get this list via the getPrefsMetadata() method. The returned list is a PrefsMetaData array. PrefsMetaData holds the following information:

  • name (unique name of preference, such as SecurityPreferences)

  • type (preference main type, such as SecurityPreferences)

  • typeSpecific (preference sub type, such as main)

  • configurationIface (Java interface that can be used for the Proxy accessor, such as com.idoox.wasp.config.SecurityModuleConfig.

Note that only preferences from installed components are available.

A WSO2 SOA Enablement Server Java client can use the getPreferences() and setPreferences() methods to get and set individual preferences. The setPreference() method returns an array of Strings containing warnings that arose during a set operation on a server. These warnings are for the user's information only.

Table 4, “Preferences in WSO2 SOA Enablement Server 6.5.4” is a list of all preferences in WSO2 SOA Enablement Server for Java 6.5.4. Example DOMs are given in Server Preferences DOM.

Table 4. Preferences in WSO2 SOA Enablement Server 6.5.4

Name Type Specific Type Java Configuration Interface
ConfigStore moduleConfigStorecom.idoox.config.xml.ConfigStoreConfig
RegistrymoduleRegistrycom.idoox.wasp.server.config.ServiceManagerConfig
HotDeploymentmoduleHotDeployercom.systinet.wasp.admin.hotdeploy.HotDeployerConfig
DefaultProtocolPropertiespreferencesmaincom.systinet.wasp.PreferencesConfig
SecurityPreferencessecurityPreferencesmaincom.idoox.wasp.config.SecurityModuleConfig
SecurityPropertiessecurityPreferencesmaincom.systinet.wasp.mgmt.preferences.security.Properties
SecurityUpdateablePolicysecurityPreferencesmaincom.systinet.wasp.mgmt.preferences.security.UpdateablePolicy
SecurityAccessControllerssecurityPreferencesmaincom.systinet.wasp.mgmt.preferences.security.AccessControllers
SecurityPStoreInitParamssecurityPreferencesmaincom.systinet.wasp.mgmt.preferences.security.PStoreInitParams
SecurityProviderssecurityPreferencesmaincom.systinet.wasp.mgmt.preferences.security.SecurityProviders
SecurityHttpDigestsecurityProviderPreferencesHttpDigestorg.idoox.wasp.security.http.digest.HttpDigestConfig
SecurityKerberosProvidersecurityProviderPreferencesKerberosorg.idoox.wasp.security.kerberos.KerberosConfig
SecurityWS-SecuritysecurityProviderPreferencesWS-Securityorg.systinet.wasp.security.ws.conf.WSSEGlobalConf
TransportJdkClienttransportdefault_clientorg.idoox.transport.config.TransportConfig
TransportFileClienttransportfile_clientorg.idoox.transport.config.TransportConfig
TransportJarClienttransportjar_clientorg.idoox.transport.config.TransportConfig
TransportHTTPClienttransporthttp_clientorg.idoox.transport.config.HttpClientConfig
TransportHTTPServertransporthttp_serverorg.idoox.transport.config.HttpServerConfig
TransportSMTPClienttransportsmtp_clientorg.idoox.transport.config.SmtpClientConfig
TransportPOPClienttransportpop_clientorg.idoox.transport.config.PopClientConfig
TransportMailtransportmailorg.idoox.transport.config.MailConfig
TransportHTTPSServerhttpsPreferenceshttpsorg.idoox.transport.config.HttpsServerConfig
TransportHTTPSClienthttpsPreferenceshttpsorg.idoox.transport.config.HttpsClientConfig
TransportJMSServertransportjmsorg.idoox.transport.jms.JMSConfig
TransportJMSClienttransportjmsorg.idoox.transport.jms.JMSConfig

The Java client can get a Proxy Bean instance via several methods provided by PreferencesHelper. This Proxy Bean implements the preference's Java configuration interface. Because the Proxy Bean works on its local copy of the preference's DOM, preferences must be set back on the server when the Client finishes work. You can use AdminService.setPreferences() or PreferencesHelper.setPreferences() for this. The Java configuration interface is usually designed as a JavaBean, so it has get and set methods. These interfaces can provide methods starting with the prefixes "add" and "new". These methods are used to manage lists in preferences. A newXXX() method creates a new instance and an addXXX() adds a newly created instance into a list. The following is an example using PreferencesHelper for simpler work with AdminService.

Example 6. Using PreferencesHelper

package example.management.admin;

import com.idoox.transport.config.AccountStoreConfig;
import com.idoox.transport.config.HttpClientConfig;

import com.systinet.wasp.mgmt.preferences.PreferencesHelper;

import org.systinet.wasp.mgmt.AdminService;
import org.systinet.wasp.webservice.Registry;

import java.net.InetAddress;


public class ServerPreferencesClient {
  public static void main(String[] args) throws Exception {
    // lookup service
    String serviceURI = "http://" +
      InetAddress.getLocalHost().getHostName() +
      ":6060/mgmt/AdminService/wsdl";
    AdminService adminService = (AdminService) Registry.lookup(serviceURI,
        AdminService.class);

    // get HTTPClient preference bean
    HttpClientConfig httpClientConfig = 
        (HttpClientConfig) PreferencesHelper.getPreferenceBeanByName(
                               adminService,
                               "TransportHTTPClient");

    // set http client default time-out to 10 minutes
    httpClientConfig.setDefaultTimeout(10 * 60 * 1000);

    // set http client proxy host and proxy port to waspproxy.wso2.com:8080
    httpClientConfig.setProxyHost("waspproxy.wso2.com");
    httpClientConfig.setProxyPort(8080);

    // set HTTPClient preference back to the server
    PreferencesHelper.setPreferences(adminService, httpClientConfig);
  }
}

Web Services Security  Locate

Using the Admin Service, you can manage security settings remotely over SOAP for the entire WSO2 SOA Enablement Server and for specified service endpoints.

Global Security Settings  Locate

Global security settings are applied by default for all service endpoints. You make them with the org.systinet.wasp.mgmt.ServerPreferences interface of the Admin Service. The name of the preference is SecurityPreferences. The Java Proxy bean interface of the security preferences is com.idoox.wasp.config.SecurityModuleConfig, and an example DOM is located in Server Preferences DOM.

Endpoint Settings for Specified Service Endpoints  Locate

The Security Configuration can be changed for each service endpoint, using the org.systinet.wasp.mgmt.ServiceSecurity interface. With this interface, you can get/set:

  • Security providers that have to be activated for accepting incoming requests (using get/setAcceptingSecurityProvider

  • The security provider that must be activated for outgoing requests (using get/setInitiatingSecurityProvider

  • Identity associations for the service endpoint (using get/setIdentityAssociations and addIdentityAssociation

  • Authorization (enable/disable) for the service endpoint (using get/setAuthorizationRequired (serviceEndpoint, authorizationRequired)

For more information about using security with Web services, see the Security Guide.

Admin Service Demo  Locate

WSO2 SOA Enablement Server for Java contains a demo that shows basic Service Administration and Web Service Monitoring capabilities. This demo is located in the $WASP_HOME/demo/management/admin (%WASP_HOME%\demos\admin) directory.

The demo shows you how to use the interfaces provided by Admin Service :

  • The first interface, Service Administration, is used to obtain all the deployed service instances on the server runtime. Then service endpoints for these service instances are determined.

  • The Service Monitoring interface is used to enable data throughput monitoring of the Admin Service, to retrieve the monitoring log from the server and to remove data from the throughput monitor.



Previous
Next