Confluence Docs 3.0 : RPC Plugins This page last changed on Nov 03, 2008 by smaddox.
| Availability RPC plugin modules are implemented in Confluence 1.4 and later.
RPC plugins allow you to deploy arbitrary SOAP or XML-RPC services within Confluence. These services may be completely independent of Confluence, or may take advantage of the Confluence APIs to provide a remote, programmatic interface to the Confluence server. Confluence's packaged remote API is implemented entirely as a plugin. For more information about plugins in general, read Confluence Plugin Guide. To learn how to install and configure plugins (including macros), read Installing and Configuring Plugins Manually. For an introduction to writing your own plugins, read Writing Confluence Plugins The Remote API packaged with Confluence is documented at Remote API Specification ## XML-RPC Plugins Here is an example `atlassian-plugin.xml` file containing a single XML-RPC service:
    <atlassian-plugin name="Sample XML-RPC" key="confluence.extra.xmlrpc">
        ...
        <rpc-xmlrpc key="helloworld-xmlrpc"
                    name="Hello World XML-RPC"
                    class="com.atlassian.confluence.extra.helloworldrpc.HelloWorld">
            <description>A public example XML-RPC service</description>
            <service-path>helloworld</service-path>
        </rpc-xmlrpc>
        ...
    </atlassian-plugin>
the class attribute defines the class that will be servicing XML-RPC requests. One instance of this class will be instantiated, and all of its public methods will be made available remotely. The instance is autowired from the Spring context. the service-path attribute is the method-prefix that is used to determine which XML-RPC method calls are routed to this plugin. Confluence listens for XML-RPC requests at a single end-point. If your server is deployed at http://www.example.com then all XML-RPC requests must be made to http://www.example.com/rpc/xmlrpc. As such, the service-path is used to distinguish which plugin each request is directed at. If your RPC implementing class has a method `provideGreeting()`, and a service-prefix of `helloworld`, then the XML-RPC method call will be `helloworld.provideGreeting()`.
| XML-RPC Interfaces The XML-RPC specification is more limited than Java code. in particular: all method parameters in the class you have deployed must take as arguments, and return as values only the "XML-RPC-friendly types" listed below null is not a valid XML-RPC type, so you must never send null as an argument, or return null as a value void is not a valid XML-RPC return type, so all methods exposed via XML-RPC must return some value
Valid types for use as arguments in methods exposed via XML-RPC, or as return values from XML-RPC methods are: `int` `boolean` `java.lang.String` `double` `java.util.Date` `java.util.Hashtable` `java.util.Vector` `byte[]` The object wrappers for the primitive types (`java.lang.Integer`, `java.lang.Boolean`, etc) may be used as return values, but not as method arguments. For more information, see: http://ws.apache.org/xmlrpc/types.html ## SOAP Plugins Here is an example `atlassian-plugin.xml` file containing a single SOAP service:
    <atlassian-plugin name="Sample XML-RPC" key="confluence.extra.xmlrpc">
        ...
        <rpc-soap key="helloworld-soap" name="Hello World SOAP" class="com.atlassian.confluence.extra.helloworldrpc.HelloWorld">
            <description>A public example SOAP service</description>
            <service-path>helloworld</service-path>
            <published-interface>com.atlassian.confluence.extra.helloworldrpc.HelloWorldPublic</published-interface>
        </rpc-soap>
        ...
    </atlassian-plugin>
the class attribute defines the class that will be servicing SOAP requests. One instance of this class is instantiated and autowired from the Spring context. the service-path element defines the SOAP service-path for this plugin, and where its WSDL file will be located. the published-interface element defines a Java interface that will be exposed via the SOAP service. The class defined in the class attribute must implement this interface. Confluence listens for SOAP requests at a single end-point. If your server is deployed at http://www.example.com then all XML-RPC requests must be made to http://www.example.com/rpc/soap. The preferred method for calling a SOAP service on Confluence is by parsing the WSDL file that is generated automatically for any deployed SOAP plugin. If your plugin has a service-path of `helloworld`, its WSDL file will be available at http://www.example.com/rpc/soap/helloworld.wsdl Unlike XML-RPC, SOAP can accept and return complex types. ## RPC Authentication Confluence supplies a very simple, token-based authentication service for its remote API. Users log in over the remote interface using a `login(username, password)` method, and are supplied with a String token. This String token is then supplied as the first argument of any subsequent remote call, to authenticate the user with their previous login. More information about this protocol can be found in the Remote API Specification documentation. Any RPC plugin can take advantage of the authentication service. To do so you must make some changes to your remote service objects, and to the configuration. Here is an `atlassian-plugin.xml` containing SOAP and XML-RPC services that require authentication:
    <atlassian-plugin name="Sample XML-RPC" key="confluence.extra.xmlrpc">
        ...
        <rpc-xmlrpc key="helloworldsecure-xmlrpc"
                    name="Secure Hello World XML-RPC"
                    class="com.atlassian.confluence.extra.helloworldrpc.HelloWorldSecureImpl">
            <description>An example XML-RPC service that requires a login</description>
            <service-name>HelloWorldPublic</service-name>
            <service-path>helloworld-secure</service-path>
            <published-interface>com.atlassian.confluence.extra.helloworldrpc.HelloWorldSecure</published-interface>
            <authenticate>true</authenticate>
        </rpc-xmlrpc>

        <rpc-soap key="helloworldsecure-soap"
                  name="Secure Hello World SOAP"
                  class="com.atlassian.confluence.extra.helloworldrpc.HelloWorldSecureImpl">
            <description>An example SOAP service that requires a login</description>
            <service-name>HelloWorldPublic</service-name>
            <service-path>helloworld-secure</service-path>
            <published-interface>com.atlassian.confluence.extra.helloworldrpc.HelloWorldSecure</published-interface>
            <authenticate>true</authenticate>
        </rpc-soap>
        ...
    </atlassian-plugin>
An authenticated XML-RPC service requires an additional published-interface element that behaves like the published-interface element in the SOAP plugin: you must supply a Java Interface to represent which methods of your plugin class are being exposed remotely. The class represented by the class attribute must implement this interface. There are two changes you have to make to your remote service objects (and their published interfaces) to allow them to take advantage of authentication: You must implement the `String login(String username, String password)` and `boolean logout(String token)` methods in `com.atlassian.confluence.rpc.SecureRpc`. However, since these methods will be intercepted by the Confluence RPC framework, they will never actually be called on your object. As such, you can leave the implementations empty. All methods in your published interface must have an initial argument that is a String (the authentication token). This token will also be intercepted by the Confluence RPC framework. Your code must not rely on this token having any value by the time the method is called on your plugin. If you are providing an authenticated service, the logged-in User will be available to you from `com.atlassian.confluence.user.AuthenticatedUserThreadLocal.getUser()`
| If anonymous RPC is enabled for your server, the logged-in user may be `null`
## Hibernate Session If you use the Confluence API within your plugin you will probably need to create a Hibernate session, and start a transaction. Getting an error like: `net.sf.hibernate.HibernateException: Could not initialize proxy - the owning Session was closed` is one indication. Using the HelloWorld example above: The class which implements your service needs to delegate each call to another object, which will be supplied when the HelloWorld instance is autowired.
    class HelloWorld implements HelloWorldPublic
    {
        private HelloWorldDelegator helloWorldDelegator;

        public int doSomething(String arg)
        {
            return helloWorldDelegator.doSomething(arg);
        }

        public void setHelloWorldDelegator(HelloWorldHandler helloWorldDelegator)
        {
            this.helloWorldDelegator = helloWorldDelegator;
        }
    }
HelloWorldDelegator contains the actual implementation of your service. It implements the same interface as HelloWorld, i.e. HelloWorldPublic. It is declared as a Spring bean, wrapped in a transaction:
        <component name="HelloWorld SOAP Service core delegator"
            key="helloWorldDelegatorTarget"
            class="com.atlassian.confluence.extra.helloworldrpc.HelloWorldDelegator"/>

        <spring key="helloWorldDelegator" class="org.springframework.transaction.interceptor.TransactionProxyFactoryBean">
            <property name="transactionManager">
                <ref local="transactionManager"/>
            </property>
            <property name="target">
                <ref local="helloWorldDelegatorTarget"/>
            </property>
            <property name="transactionAttributes">
                <props>
                    <prop key="*">PROPAGATION_REQUIRED</prop>
                </props>
            </property>
            <property name="proxyInterfaces">
                <value>com.atlassian.confluence.extra.helloworldrpc.HelloWorldPublic</value>
            </property>
            <property name="postInterceptors">
                <list>
                    <ref local="profilingInterceptor"/>
                </list>
            </property>
        </spring>
## Example Example XML-RPC and SOAP plugins are available in the Confluence distribution under `plugins/helloworldrpc`. It can also be found here The full source to the Confluence remote API plugin can be found in the Confluence distribution under `plugins/confluencerpc`. The Confluence Remote API uses a mixture of RPC plugins andComponent Plugins, along with a simple mechanism to serialize Java objects into an XML-RPC compatible struct, to serve the same API over both SOAP and XML-RPC. We strongly recommend you use a similar mechanism to provide both RPC APIs.

Document generated by Confluence on Nov 05, 2009 23:34