View source for Lyo/LyoOSLC4J

= Lyo OSLC4J =

== What is OSLC4J? ==

OSLC4J is a Java toolkit for building [http://open-services.net/ Open Services for Lifecycle Collaboration] providers and consumers.  It includes:

* annotations to decorate Java objects with OSLC attributes
* annotations to assist with resource preview UIs (compact rendering)
* built-in support for service provider and resource shape documents
* libraries to simplify service provider and consumer development
* sample applications, including an OSLC Registry (catalog) application and a Change Management provider implementation
* Tests for the sample applications to complement the [[Lyo/LyoTestSuite|Lyo OSLC Test Suite]]

== Components == 

* OSLC4J - The core component providing OSLC annotation and model support (<tt>org.eclipse.lyo.oslc4j.core / oslc4j-core</tt>)
* Apache Jena Provider - A library to assist with serialization/de-serialization of OSLC-annotated Java objects to/from RDF XML (<tt>org.eclipse.lyo.oslc4j.core / oslc4j-jena-provider</tt>).
* Apache Wink Json4J Provider - A library to assist with serialization/de-serialization of OSLC-annotated Java objects to/from JSON (<tt>org.eclipse.lyo.oslc4j.core / oslc4j-json4j-provider</tt>).
* Apache Wink JAX-RS Provider - Utility classes, including an OSLC REST Client, to facilitate development using the Apache Wink JAX-RS implementation.

The Apache Jena<ref>http://incubator.apache.org/jena/</ref> and Apache Wink<ref>http://incubator.apache.org/wink/</ref> components are the built-in providers for RDF, RDF XML, JSON and JAX-RS.   Additional providers could be implemented using technologies such as OpenRDF and Jersey.

== Sample code == 

=== Annotation sample ===
<source lang="java">
    //sample simple string attribute (dcterms:description, as in http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixA#Dublin_Core_Properties)

    @OslcDescription("Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content.")
    @OslcPropertyDefinition(OslcConstants.DCTERMS_NAMESPACE + "description")
    @OslcTitle("Description")
    @OslcValueType(ValueType.XMLLiteral)
    public String getDescription()
    {
        return description;
    }  

    //sample relationship attribute (oslc_cm:affectsTestResult, as in http://open-services.net/bin/view/Main/CmSpecificationV2#Resource_ChangeRequest)

    @OslcDescription("Associated QM resource that is affected by this Change Request.")
    @OslcName("affectsTestResult")
    @OslcPropertyDefinition(Constants.CHANGE_MANAGEMENT_NAMESPACE + "affectsTestResult")
    @OslcRange(Constants.TYPE_TEST_RESULT)
    @OslcReadOnly(false)
    @OslcTitle("Affects Test Results")
    public URI[] getAffectsTestResults()
    {
        return affectsTestResults.toArray(new URI[affectsTestResults.size()]);
    }
</source>

=== JAX-RS method sample ===

This illustrates implementation of an OSLC-CM (REST) server/provider
<source lang="java">
    //support GET for a specific OSLC ChangeRequest

    @GET
    @Path("{changeRequestId}")
    @Produces({OslcMediaType.APPLICATION_RDF_XML, OslcMediaType.APPLICATION_XML, OslcMediaType.APPLICATION_JSON})
    public ChangeRequest getChangeRequest(@Context                      final HttpServletResponse httpServletResponse,
                                          @PathParam("changeRequestId") final String              changeRequestId)
    {
        final ChangeRequest changeRequest = Persistence.getChangeRequest(changeRequestId);
        if (changeRequest != null)
        {
            changeRequest.setServiceProvider(ServiceProviderSingleton.getServiceProviderURI());
            setETagHeader(getETagFromChangeRequest(changeRequest), httpServletResponse);
            return changeRequest;
        }
        throw new WebApplicationException(Status.NOT_FOUND);
    }

    //support POST to create a new ChangeRequest

    @POST
    @Consumes({OslcMediaType.APPLICATION_RDF_XML, OslcMediaType.APPLICATION_XML, OslcMediaType.APPLICATION_JSON})
    @Produces({OslcMediaType.APPLICATION_RDF_XML, OslcMediaType.APPLICATION_XML, OslcMediaType.APPLICATION_JSON})
    public Response addChangeRequest(@Context final HttpServletRequest  httpServletRequest,
    		                         @Context final HttpServletResponse httpServletResponse,
                                              final ChangeRequest       changeRequest)
           throws URISyntaxException
    {
        final long identifier = Persistence.getNextIdentifier();
        final URI about = new URI(httpServletRequest.getScheme(),
                                  null,
                                  httpServletRequest.getServerName(),
                                  httpServletRequest.getServerPort(),
                                  httpServletRequest.getContextPath() + "/changeRequests/" + identifier,
                                  null,
                                  null);
        changeRequest.setAbout(about);
        changeRequest.setIdentifier(String.valueOf(identifier));
        changeRequest.setServiceProvider(ServiceProviderSingleton.getServiceProviderURI());

        final Date date = new Date();

        changeRequest.setCreated(date);
        changeRequest.setModified(date);

        Persistence.addChangeRequest(changeRequest);
        setETagHeader(getETagFromChangeRequest(changeRequest), httpServletResponse);

        return Response.created(about).entity(changeRequest).build();
    }
</source>
== Getting started with OSLC4J ==

* See [http://eclipse.org/lyo/download.php the Lyo download page] for zips of OSLC4J and its prerequisite open source libraries.
* See [[Lyo/BuildingOSLC4J|Setting up OSLC4J]] for information on setting up a development environment and building the OSLC4J code samples.
* See the latest [http://download.eclipse.org/lyo/docs/1.0/apidocs/ Javadoc for OSLC4J].

== See also ==
* [http://en.wikipedia.org/wiki/Java_annotation Java annotations]