ManagementService 1.0 : Creating a Java client

{toc}

(((The following example is created with NetBeans IDE 6.8)))

In this example we are going to communicate with the management service v1.0 in java. The webservice is located at the following location:
* [http://services.companywebcast.com/management/1.0/managementservice.svc?wsdl]

The NetBeans project containing the sourcecode can be downloaded here:
[{UP}ManagementService_1.0_Java/JavaManagementServiceClient.zip|Sample sourcecode]

==Web Service Reference==

The following steps need to be performed to generate a proxy:
* Open NetBeans IDE
* Create a project (here a normal java application)
* Select the Project tab
* Right-click the "Web Service References" node
* Select "New > Web Service Client"
* Enter the WSDL url mentioned above
* Make sure "Client Style" is set to "JAX-WS Style"
* Select "Finish"

===Custom settings===

The generated proxy has code that handles special xml serialization cases like xml elements that has a minoccurence of 0 for example. The code to handle such scenarios needs to be able to influence to xml serializer. Our webservice treats the non existance of a xml element and nill values the same. This also applies to (empty) collections. The result is that is is more easy to make use of the web service without the need to set each and every property to certain value.

This means that we can change the way the java proxy handles serialisation of certain elements. The client code looks prettier and is more easy to read with the setting '''generateElementProperty''' set to '''false'''.

* Create a custom settings file at the same location as the downloaded WSDL file (here: bindings.jxb)
* Right-click the generated Web Service Reference and select "Edit Web Service Attributes"
* Select the "WSDL Customazation" tab
* Scroll all the way down and open "External Binding Files"
* Add the bindings file (bindings.jxb)
* Click "OK"

The content for the file "bindings.jxb":
<code xml><jxb:bindings
   version="2.0"
   xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
   xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <jxb:globalBindings generateElementProperty="false" />
</jxb:bindings>
</code>

(((The proxy should now be refreshed and be regenerated. If not you could refresh manually by right-clicking the Web Service Reference and select "Refresh".)))


==Sample code==
The following example code does the following:
* Retrieve the customer list
* Retrieve the profiles for a customer
* Create a webcast for a customer based on a profile
* Retrieve a webcast
* Changing the webcast title and saving it
* Added a topic and saving it
* Deleting a webcast


<code java>
    int PageSize = 100;

    String username = "testuser";
    String password = "0123456789";

    cwcmanagementsvc.ManagementService_Service service = new ManagementService_Service();

    int currentPage = 0;

    ManagementService port = service.getBasicHttpBindingManagementService();

    // All methods return with a result code. Zero means succes, negative
    // means server error and positive is a client error.

    Holder<Integer> result = new Holder<Integer>();

    // First retrieve the available customers for this user account and
    // lets just use the first for all following methods.

    Holder<CustomerSummaries> customers = new Holder<CustomerSummaries>();

    port.customerList(
            username,
            password,
            currentPage,
            PageSize,
            result,
            customers);

    if(result.value!=0) throw new Exception("Could not retrieve customer list. Reason: " + result.value);

    if(customers.value.getCustomerSummary().isEmpty()) throw new Exception("No customers.");

    System.out.println("Available customers:");

    for(int i=0;i<customers.value.getCustomerSummary().size();i++)
    {
        CustomerSummary c = customers.value.getCustomerSummary().get(i);
        System.out.format(" - %s\r\n", c.getName());
    }


    String customerId = customers.value.getCustomerSummary().get(0).getId();

    // Now lets retrieve the available webcast profiles for this customers
    // and select the first profile.

    Holder<Profiles> profiles = new Holder<Profiles>();

    port.profileList(
            username,
            password,
            customerId,
            result,
            profiles);

    if(result.value!=0) throw new Exception("Could not retrieve profile list. Reason: " + result.value);

    if(profiles.value.getProfile().isEmpty()) throw new Exception("No profiles.");

    System.out.println("Available profiles:");

    for(int i=0;i<profiles.value.getProfile().size();i++)
    {
        Profile p = profiles.value.getProfile().get(i);
        System.out.format(" - %s\r\n", p.getTitle());
    }

    String profileId = profiles.value.getProfile().get(1).getId();

    // Here we are going to create a webcast for a specific customer with
    // a specific profile. This will create a webcast that we can later
    // retrieve to extend with additional data.

    Holder<String> webcastCode = new Holder<String>();

    GregorianCalendar plannedStartUtc;

    plannedStartUtc = new GregorianCalendar(2011, 1, 1, 13, 5 );

    // javax.xml.datatype
    XMLGregorianCalendar xmlPlannedStartUtc = DatatypeFactory.newInstance().newXMLGregorianCalendar( plannedStartUtc );

    port.webcastCreate(
            username,
            password,
            customerId,
            profileId,
            xmlPlannedStartUtc,
            result,
            webcastCode);

    if(result.value!=0) throw new Exception("Could not create webcast. Reason: " + result.value );

    System.out.format("Webcast created succesfully (code: %s)\r\n", webcastCode.value);

    // We are going to just retrieve the webcast with the key that we got on
    // the create method.

    Holder<Webcast> webcast = new Holder<Webcast>();

    port.webcastGet(
            username,
            password,
            webcastCode.value,
            result,
            webcast);

    if(result.value!=0) throw new Exception("Could not retrieve webcast data. Reason: " + result.value);

    System.out.format("Webcast %s retrieved succesfully.\r\n", webcastCode.value);

    // A webcast can have localized literals. For example if a webcast is
    // in Dutch and English the topics need to be specified in two languages.
    // The available languages can be determined via the LanguageCodes property.

    java.util.List<String> codes = webcast.value.getLanguageCodes().getString();

    if(codes.size()!=1) throw new Exception("Only one language is supported in this sample.");

    if(!codes.get(0).equalsIgnoreCase("nl")) throw new Exception("Only Dutch is supported in this sample.");

    int dutchIndex = 0;

    // The system works with optimistic concurrency control. We use this so
    // that modifications done by another user or process or the system
    // itself will not result in data loss. The value that is used to compare
    // versions is held in the webcastRevision argument.
    //
    // Here we are just going to save the webcast data that we previously
    // retrieved from the system. We just change the webcast title and the
    // reference.

    String webcastTitle = "Ramon " + webcast.value.getCode();
    webcast.value.getLocalization().getWebcastData().get(dutchIndex).setTitle(webcastTitle);
    webcast.value.setReference(webcastTitle);

    Holder<String> webcastRevision = new Holder<String>();

    port.webcastSave(
            username,
            password,
            webcast.value,
            result,
            webcastRevision);

    if(result.value!=0) throw new Exception("Could not save webcast after creation. Reason: " + result.value);

    System.out.println("Webcast with changed title saved succesfully.");

    webcast.value.setRevision(webcastRevision.value);

    // Now we are going to change the webcast data. Here we are going to
    // add an additional topic.

    TopicsModule tm = webcast.value.getTopicsModule();

    Topic topic = new Topic();
    topic.setTitle("A nice topic");
    topic.setDescription("This topic is as nice as it can possibly be.");

    tm.getTopics().getTopics().get(dutchIndex).getTopic().add(topic);

    // Now save the modified webcast data.

    port.webcastSave(
            username,
            password,
            webcast.value,
            result,
            webcastRevision);

    if(result.value!=0) throw new Exception("Could not save webcast after previous save. Reason: " + result.value);

    System.out.println("Webcast with added topic saved succesfully.");

    // When we want to delete a webcast we also need the revision code as
    // this is also a modification. It could be that something or someone
    // else has modified the data so that would first require an update of
    // the data and check if a delete would still be appropriate.

    result.value = port.webcastDelete(
            username,
            password,
            webcastCode.value,
            webcastRevision.value);

    if(result.value!=0) throw new Exception("Could not delete webcast. Reason: " + result.value);

    System.out.println("Webcast deleted succesfully.");
</code>

==References==
# [http://java.sun.com/webservices/reference/tutorials/wsit/doc/DataBinding5.html]
# [http://java.sun.com/javaee/5/docs/tutorial/doc/bnbbf.html]
Companywebcast API Wiki

Navigation

ManagementService 1.0 : Creating a Java client
