1 | | gggg |
| 1 | [[PageOutline]] |
| 2 | = Trac XML-RPC Plugin = |
| 3 | |
| 4 | == ''Note about 0.11 compatibility'' == |
| 5 | |
| 6 | ''You can [query:component=XmlRpcPlugin&release=0.11 check out the tickets] that users have created, there may be a solution to your problem.'' Especially #1075 states that it works out of the box with Eclipse-3.3 and Mylyn. |
| 7 | |
| 8 | == Description == |
| 9 | |
| 10 | This plugin allows Trac plugins to export select parts of their interface via XML-RPC. |
| 11 | |
| 12 | It also includes some exported functions for manipulating tickets, with plans to include interfaces to other parts of Trac's API. |
| 13 | |
| 14 | The browsable XML-RPC URI suffix is /xmlrpc, however most XML-RPC clients should use the authenticated URL suffix |
| 15 | /login/xmlrpc as this is correctly authenticated by Trac. |
| 16 | |
| 17 | '''Note''': if you do want to use /xmlrpc and unauthenticated access, you must grant the XML_RPC permission to the 'anonymous' user. |
| 18 | |
| 19 | [http://www.jspwiki.org/Wiki.jsp?page=WikiRPCInterface2 WikiRPC API] is complete, mostly thanks to [wiki:mgood]. |
| 20 | |
| 21 | Ticket API is also complete, with the following types exported: component, version, milestone, type, status, resolution, priority and severity. |
| 22 | |
| 23 | For example, for TracHacks the URIs are http://trac-hacks.org/xmlrpc and http://trac-hacks.org/login/xmlrpc (must be authenticated). |
| 24 | |
| 25 | == Todo == |
| 26 | |
| 27 | Outstanding tasks are roadmap, timeline, user management (e.g. get a (filtered) user list to assign a task in [http://eclipse.org/mylyn/ mylyn]), plugin management (?)...plus probably more. |
| 28 | |
| 29 | == Installation == |
| 30 | This plugin ''requires'' at least Trac 0.10. It will not work with Trac 0.9.x or earlier. |
| 31 | |
| 32 | Install in the same manner as any other Trac plugin: |
| 33 | {{{ |
| 34 | # python setup.py bdist_egg |
| 35 | # cp dist/*.egg /srv/trac/env/plugins |
| 36 | }}} |
| 37 | |
| 38 | or if you want it to be installed for all Trac environments: |
| 39 | |
| 40 | {{{ |
| 41 | # easy_install /path/to/unpacked/xmlrpcplugin.zip/0.10 |
| 42 | }}} |
| 43 | |
| 44 | (You might want to use ''easy_install -Z'' so that it doesn't need to be unpacked when it's called.) |
| 45 | |
| 46 | You will also probably need to enable the plugin in your environments trac.ini: |
| 47 | |
| 48 | {{{ |
| 49 | [components] |
| 50 | tracrpc.* = enabled |
| 51 | }}} |
| 52 | |
| 53 | == Bugs/Feature Requests == |
| 54 | |
| 55 | Existing bugs and feature requests for XmlRpcPlugin are [query:status!=closed&component=XmlRpcPlugin&order=priority here]. If you have any issues, create a [/newticket?component=XmlRpcPlugin&owner=athomas new ticket]. |
| 56 | |
| 57 | == Troubleshooting == |
| 58 | |
| 59 | === Problems when AccountManagerPlugin is enabled === |
| 60 | If you have the AccountManagerPlugin enabled and you followed their advise/example to disable the standard login module with |
| 61 | {{{ |
| 62 | [components] |
| 63 | trac.web.auth.LoginModule = disabled |
| 64 | }}} |
| 65 | the /login/xmlrpc URL for authorized access will not work as expected. Every access will look like anonymous access. |
| 66 | |
| 67 | You can use the HttpAuthPlugin to correct this. |
| 68 | |
| 69 | === Problems with ''Digest'' HTTP authentication === |
| 70 | |
| 71 | The `xmlrpclib.ServerProxy` client - as demonstrated in the following examples - will not work with a ''Digest''-based HTTP authentication: you need to set up a ''Basic'' HTTP authentication on server side to make the examples work. |
| 72 | |
| 73 | If you use the standalone Trac daemon, this means that you cannot use the `tracd -a` option (htdigest authentication file). Use `trac --basic-auth` (htpasswd authentication file) instead. |
| 74 | |
| 75 | === Problems with mod_python, Apache, python 2.4 === |
| 76 | |
| 77 | XmlRpcPlugin might not work with Apache and python 2.4 as explained in [http://trac.edgewall.org/wiki/TracInstall#Requirements TracInstall]. Use python 2.5 if you want to run Trac with mod_python. |
| 78 | |
| 79 | == Download and Source == |
| 80 | |
| 81 | Download the [download:xmlrpcplugin zipped source], check out the [/svn/xmlrpcplugin source using Subversion] or [source:xmlrpcplugin browse the source] with Trac. |
| 82 | |
| 83 | == Example == |
| 84 | |
| 85 | === Python End-User Usage === |
| 86 | |
| 87 | Obtain and print a list of XML-RPC exported functions available to my user: |
| 88 | |
| 89 | {{{ |
| 90 | #!python |
| 91 | import xmlrpclib |
| 92 | |
| 93 | server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac-dev/login/xmlrpc") |
| 94 | for method in server.system.listMethods(): |
| 95 | print method |
| 96 | print '\n'.join([' ' + x for x in server.system.methodHelp(method).split('\n')]) |
| 97 | print |
| 98 | print |
| 99 | }}} |
| 100 | |
| 101 | The same example using `system.multicall()`. This reduces network and server |
| 102 | load by compacting all of the `system.methodHelp()` calls into one HTTP POST. |
| 103 | |
| 104 | {{{ |
| 105 | #!python |
| 106 | import xmlrpclib |
| 107 | |
| 108 | server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac/devel/login/xmlrpc") |
| 109 | |
| 110 | multicall = xmlrpclib.MultiCall(server) |
| 111 | for method in server.system.listMethods(): |
| 112 | multicall.system.methodHelp(method) |
| 113 | |
| 114 | for help in multicall(): |
| 115 | lines = help.splitlines() |
| 116 | print lines[0] |
| 117 | print '\n'.join([' ' + x for x in lines[2:]]) |
| 118 | print |
| 119 | |
| 120 | }}} |
| 121 | |
| 122 | List all tickets that are owned by athomas, using the XML-RPC multicall system |
| 123 | to issue multiple RPC calls with one HTTP request: |
| 124 | |
| 125 | {{{ |
| 126 | #!python |
| 127 | import xmlrpclib |
| 128 | |
| 129 | server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac/devel/login/xmlrpc") |
| 130 | |
| 131 | multicall = xmlrpclib.MultiCall(server) |
| 132 | for ticket in server.ticket.query("owner=athomas"): |
| 133 | multicall.ticket.get(ticket) |
| 134 | print map(str, multicall()) |
| 135 | }}} |
| 136 | |
| 137 | Access the Wiki with [http://www.jspwiki.org/Wiki.jsp?page=WikiRPCInterface2 WikiRPC] |
| 138 | {{{ |
| 139 | #!python |
| 140 | import xmlrpclib |
| 141 | |
| 142 | server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac-dev/login/xmlrpc") |
| 143 | |
| 144 | # print the content of WikiStart |
| 145 | print server.wiki.getPage("WikiStart") |
| 146 | |
| 147 | # print WikiStart as HTML |
| 148 | print server.wiki.getPageHTML("WikiStart") |
| 149 | |
| 150 | # write to the SandBox page from a text file |
| 151 | sandbox_content = file("sandbox.txt").read() |
| 152 | server.wiki.putPage("SandBox", sandbox_content, {"comment": "testing the WikiRPC interface"}) |
| 153 | }}} |
| 154 | |
| 155 | Add an attachment to WikiStart: |
| 156 | |
| 157 | {{{ |
| 158 | #!python |
| 159 | import xmlrpclib |
| 160 | |
| 161 | server = xmlrpclib.ServerProxy("http://athomas:password@localhost:8080/trunk/login/xmlrpc") |
| 162 | |
| 163 | server.wiki.putAttachment('WikiStart/t.py', xmlrpclib.Binary(open('t.py').read())) |
| 164 | }}} |
| 165 | |
| 166 | === Using from C# === |
| 167 | |
| 168 | See DotNet. |
| 169 | |
| 170 | === Using from Java === |
| 171 | |
| 172 | See [/attachment/wiki/XmlRpcPlugin/trac_xml_rpc_example_java.zip?format=raw this example zip file] |
| 173 | |
| 174 | === API Usage === |
| 175 | |
| 176 | See the [source:xmlrpcplugin/0.10/tracrpc/api.py source] for details. |
| 177 | |
| 178 | == Screenshot == |
| 179 | |
| 180 | If the HTTP request to this URI is not XML, the XmlRpcPlugin will list all exported functions that the current user has permission to use. |
| 181 | |
| 182 | [[Image(tracrpc.png)]] |
| 183 | |
| 184 | == Change Log == |
| 185 | |
| 186 | [[ChangeLog(/xmlrpcplugin, 5)]] |
| 187 | |
| 188 | == Author/Contributors == |
| 189 | |
| 190 | '''Author:''' [wiki:athomas] [[BR]] |
| 191 | '''Contributors:''' [wiki:mgood] [[BR]] |
| 192 | |
| 193 | [[TagIt(plugin,athomas,mgood,alpha,0.10)]] |