TinyWS

TinyWS is a Java servlet which gives access to methods via SOAP over HTTP. Function signatures and data structures are exported via WSDL (hence the name TinyWS which stands for a Tiny WebService).

Howto

  1. Download the latest TinyWS release
  2. Deploy the TinyWS-X.Y.war file at your servlet container (e.g. Tomcat)
  3. Download Codec from the Apache Commons Project into your $CATALINA_HOME/lib folder (only for TinyWS >= 2.0)
  4. Download FileUpload from the Apache Commons Project into your $CATALINA_HOME/lib folder (only for TinyWS >= 2.0)
  5. Put a JDBC connector for your database into your $CATALINA_HOME/lib folder, eg. for MySQL (only for TinyWS >= 2.0)
  6. Create a JNDI datasource called TinyWSDB within your servlet container. Have a look at my $CATALINA_HOME/conf/Catalina/localhost/TinyWS.xml:
    <?xml version="1.0" encoding="UTF-8"?>
    <Context path="/TinyWS">
    <Resource name="/jdbc/TinyWSDB" type="javax.sql.DataSource"
        driverClassName="com.mysql.jdbc.Driver"
        username="tinyws" password="verysecret"
        url="jdbc:mysql://localhost:3306/TinyWSDB" />
    </Context>
    
    (only for TinyWS >= 2.0)
  7. Ensure that you can connect to the database specified by those credentials (only for TinyWS >= 2.0)
  8. Either:
    1. Write a small application that allows you to upload and delete applications within TinyWS
    2. Download or reference the url http://your.servlet.container/TinyWS/servlet/net.ogris.tinyws?wsdl in that application
    3. Call the (remote) methods TinyWSUploader.uploadApplication and TinyWSUploader.deleteApplication where appropriate
    4. Start a new Java project in your IDE, and import the file http://your.servlet.container/TinyWS/net.ogris.tinyws.annotation.jar
    5. Write the methods that you want to make accessible via SOAP; prefix each exported method with an net.ogris.tinyws.annotation.TinyWSParams annotation, which should contain an array of strings stating the method's parameter names
    6. Copy your Java classes into a new jar file as if you were building an ordinary application
    7. Upload that jar file to TinyWS by using your small application from #8.1 to #8.3
    Or:
    • Alternatively, upload your jar file through the TinyWS web interface
  9. Now you can start writing SOAP clients for Java classes by referencing http://your.servlet.container/TinyWS/servlet/your.name.space?wsdl
  10. For logging all TinyWS errors and warnings to a separate file, edit $CATALINA_HOME/conf/logging.properties. Add a new handler called 6TinyWS.org.apache.juli.FileHandler. Configure this handler:
    6TinyWS.org.apache.juli.FileHandler.level = ALL
    6TinyWS.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
    6TinyWS.org.apache.juli.FileHandler.prefix = TinyWS.
    
    Finally send all TinyWS logs to this handler:
    org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/TinyWS].level = ALL
    org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/TinyWS].handlers = 6TinyWS.org.apache.juli.FileHandler
    

About

TinyWS is a Java servlet that acts as a SOAP container. You upload compiled class files bundled into JAR archives (I call these applications although there is no need for a public static main(String[]) method). Every method within those class files will be accessible by SOAP (and WSDL) if all of the following requirements are met:

You might wonder what that TinyWSParams annotation is for. Have a look at the following method:
public String foobar(Integer a, String b) {
    return b + a;
}
The Java compiler removes the name of all parameters. In byte code the method's signature looks like public String foobar(Integer, String). To keep the name of all parameters, you have to use a TinyWSParams annotation:
@TinyWSParams({"a", "b"})
public String foobar(Integer a, String b) {
    return b + a;
}
So TinyWS can generate method descriptions using named method parameters. Another annotation type (TinyWSDoc) could be used to export your inline documentation:
package net.ogris.tinyws.test;

@TinyWSDoc("This class provides some services")
public class Test {

    @TinyWSDoc("This method does something.\n"
        + "And has a multiline documentation.\n"
        + "Cool!")
    @TinyWSParams({"a", "b"})
    public static int blabla(int a, int b) {
        return a + b;
    }
}
These TinyWSDoc annotations are put into the WSDL description and generated stubs. Keep in mind that all classes and types must be resolvable. If you are using non-base Java types:
@TinyWSParams({"a", "b"})
public Snafu foobar(Integer a, String b) {
    return new Snafu(b + a);
}
Then the class Snafu must be resolvable, which means that Actually TinyWS is my replacement for SOAP containers like Axis2, which is too heayweight in my eyes, needs support from your IDE (like an Axis project template) and does not produce reasonable WSDL descriptions. As WSDL or the automatic creation of client side stub functions is the most funny thing about SOAP (besides using just one TCP port for all the RPC communication) I had to get it right for the environments that I am occasionally working in (that is, proramming within NetBeans or Visual Studio).

Features

Wishlist

Download

TinyWS is licensed under the LGPL Version 3. See the file web/License.txt in the source distribution, which is available as http://your.servlet.container/TinyWS/License.txt on a TinyWS equipped site or read it online at http://www.gnu.org/licenses/lgpl.txt (local copy).

Source

Source code is available in SVN:

Username: svn, Password: svn