Java BDK Clients


Note:

The samples featured on this page work only for Oracle Beehive Release 2 (2.0.1.0)


This page covers the following topics:

Setup with Third Party APIs


Note:

This section does not recommend the use of one API over another. The APIs use by the examples on this page were chosen because they are commonly used.


The following steps describe how to configure HTTPClient, which is used to enable the HTTP server Oracle Beehive RESTful Web services to communicate with each other and JAXB, which marshalls and unmarshalls data between XML and value object formats.

Step 1   Download HttpClient Libraries

Download the following jar files:

Step 2   Download JAXB

Download JAXB from https://jaxb.dev.java.net/ . It contains the following libraries. Ensure that these JAXB libraries are in your class path.

  • activation.jar (This library is part of the JavaBeans Activation Framework.)

  • jaxb-api.jar

  • jaxb-impl.jar

  • jaxb-xjc.jar

  • jsr173_1.0_api.jar

Alternatively, obtain the JAXB libraries from < Oracle Beehive home >/beehive/third-party.

JAXB also contains the JAXB XJC schema binding compiler, xjc.

Step 3   Generate Value Objects Using JAXB

The following steps describe how to generate the Oracle Beehive RESTful Web services value objects using JAXB:

  1. Ensure that the JAXB libraries are in your class path.

  2. Download the following XSD files:

    • <Host name and port of your Oracle Beehive HTTP server> /comb/v1/schema-obh-xjc.xsd

    • <Host name and port of your Oracle Beehive HTTP server> /comb/v1/schema-obr.xsd

  3. Generate value objects by running the JAXB XJC schema binding compiler, xjc, with the schema files schema-obh-xjc.xsd and schema-obr.xsd and the -extension option:

    Microsoft Windows:

                                               
    <JAXB directory>\bin\xjc.bat schema-obh-xjc.xsd schema-obr.xsd -extension
                                            

    Linux and UNIX-based operating systems:

                                               
    <JAXB directory>/bin/xjc.sh schema-obh-xjc.xsd schema-obr.xsd -extension
                                            
  4. Add the classes contained in the packages com.oracle.beehive and com.oracle.beehive.rest (which you generated with xjc in the previous step) to your project.

  5. You may receive the following error message when using the generated classes:

    com.sun.istack.SAXException2: unable to marshal type "com.oracle.beehive.
                                              
    className" as an element because it is missing an @XmlRootElement annotation
                                            

    If you get this error message, manually add the @XmlRootElement annotation to the generated Java source file of className and add the following import statement:

    import javax.xml.bind.annotation.XmlRootElement;
    

    For example, suppose you encountered the following error message:

    com.sun.istack.SAXException2: unable to marshal type "com.oracle.beehive.PredicateAndSortListParameters" as an element because it is missing an @XmlRootElement annotation
    

    You would import the class javax.xml.bind.annotation.XmlRootElement and add the highlighted line to the generated source file PredicateAndSortListParameters.java as follows:

                                               
    @XmlRootElement(name="predicateAndSortListParameters")
    public class PredicateAndSortListParameters
        extends PredicateListParameters
    {
                                            

Tip:

Refer to the following site if you encounter any runtime errors while generating the value objects:

https://jaxb.dev.java.net/guide/Runtime_Errors.html



https://jaxb.dev.java.net/guide/Runtime_Errors.html

Compile the generated classes with the same JDK version you want to use to compile and run the examples.


JAXB Programming Tips

Runtime Errors Encountered While Generating Value Objects

Refer to the following site if you encounter any runtime errors while generating the value objects:

https://jaxb.dev.java.net/guide/Runtime_Errors.html

Compile the generated classes with the same JDK version you want to use to compile and run the examples.

Pooling JAXB Marshallers and Unmarshallers to Limit Memory Usage

The class JAXBQueue limits the memory usage of JAXB. Each JAXB marshaller and unmarshaller reserves a lot of memory by keeping serialization and deserialization results; they will not release the memory until another operation commences.

Creating marshallers and unmarshallers is expensive and making empty serializations and deserializations to release the memory used by the internal state is wasteful; to solve this problem, the JAXBQueue class pools JAXB resources.

This class is implemented based on the following preconditions:

  • The number of physical threads that have access to the pool is capped.

  • This cap does not change over the lifetime of the application

JAXBQueue creates a marshaller or unmarshaller each time the internal queue is empty, guaranteeing that there is at most the same number of outstanding resources as there are physical threads demanding them.

Java BDK Examples

The following table lists examples that show you how to use Oracle Beehive RESTful Web services with Java. Find the source code files in java_bdk_sample.zip:

Table 5-1 Java BDK Examples

Description Requirements Source Code Files

Prints information about the logged in user.

  • Configures HTTPClient and an Unmarshaller instance (from JAXB).

  • Calls the /my/user resource.

  • Unmarshalls the reply from the server into an OrganizationUser object, which the example uses to print out information about the currently logged in user.

Example1Authentication.java

Retrieves the folders of type HeterogeneousFolder of the logged in user.

Example2Identifiers.java

Java Samples Utility Files

Creates a team workspace.

Example3CreateObject.java

Java Samples Utility Files

Retrieves the logged in user's information with an EMPTY projection, then with a BASIC projection.

Example4Projections.java

Java Samples Utility Files

Creates a Document artifact that contains a text document.

Example5CreateContent.java

Java Samples Utility Files

Creates a Document artifact that contains a text document, then creates a Topic with a reference to the Document

  • Follow the steps described in "Setup with Third Party APIs"

  • The logged in user has a TeamWorkspace

  • The workspace has a default Documents folder

  • The logged in user is a Full Member of the workspace

Example5CreateSimpleContent.java

Java Samples Utility Files


Java Samples Utility Files

Find these files in java_bdk_sample.zip:

  • Configuration.java: Place this file in the same package as all the other examples. It specifies the HTTP host name, port number, user name, and password that all the BDK Java examples use to authenticate with and access the Oracle Beehive server. Change these values according to your Oracle Beehive deployment.

  • BDKExampleUtil.java

  • JAXBQueue.java

  • Parameter.java

  • ParameterList.java

  • ParameterType.java

  • RESTTransport.java

  • RESTTransportHTTPClient.java