Author: gmazza
Date: Tue Mar 20 21:08:46 2012
New Revision: 1303153
URL: http://svn.apache.org/viewvc?rev=1303153&view=rev
Log:
Renamed READMEs to make consists across all samples.
Added:
cxf/trunk/distribution/src/main/release/samples/jax_rs/minimal_osgi/README.txt
cxf/trunk/distribution/src/main/release/samples/oauth/README.txt
Removed:
cxf/trunk/distribution/src/main/release/samples/jax_rs/minimal_osgi/README
cxf/trunk/distribution/src/main/release/samples/oauth/README.TXT
Added:
cxf/trunk/distribution/src/main/release/samples/jax_rs/minimal_osgi/README.txt
URL:
http://svn.apache.org/viewvc/cxf/trunk/distribution/src/main/release/samples/jax_rs/minimal_osgi/README.txt?rev=1303153&view=auto
==============================================================================
---
cxf/trunk/distribution/src/main/release/samples/jax_rs/minimal_osgi/README.txt
(added)
+++
cxf/trunk/distribution/src/main/release/samples/jax_rs/minimal_osgi/README.txt
Tue Mar 20 21:08:46 2012
@@ -0,0 +1,118 @@
+Minimal OSGI Sample Documentation
+=================================
+
+Introduction
+-------------
+
+You may not know it but CXF actually has an OSGI bundle for JAX-RS.
Unfortunately, documentation on how to use it is very hard to come by.
+This sample demonstrates the minimal amount of bundles necessary and code
tweaks required to get a sample that uses CXF's JAX-RS
+implementation to work correctly in an OSGI environment.
+
+This is not necessarily the best way to achieve the above. In particular, use
of CXF-specific syntax (as much as possible). However, I believe it's a
+good balance between code readability and simplicity.
+
+Introduction
+Pre-requisites
+Sample walkthrough
+ Code walkthrough
+ Deployment notes
+Running the sample
+Bundles
+
+Pre-requisites
+--------------
+
+To take advantage of this sample, you should have a working knowledge of the
following:
+
+JSR-311 JAX-RS
+* Maven
+* OSGI
+* Servlet
+
+Sample walkthrough
+------------------
+
+Code walkthrough
+
+Let's start off with a basic JSR-311 JAX-RS application that you would like to
deploy in an OSGI environment:
+* SampleResource
+* SampleApplication
+
+With this sample application, if you go to a URL that looks like the
following, you should get a "My Sample Text" in the browser:
+ http://<host>:<port>/
+
+To get this application running in an OSGi environment, when the HTTP OSGI
service starts up, CXFNonSpringJaxrsServlet needs to be
+registered. This is accomplished in the code found inside the Activator. We
use ServiceTracker to take care of the hard work of monitoring
+when the HTTP OSGI service comes up and registering ourselves to it.
+
+The big gotcha here though is our application is in one bundle but CXF is
contained within another bundle. Because OSGI creates one
+classloader for each bundle and CXF uses reflection to discover applications,
this discovery won't work in an OSGI environment. To get around
+this limitation, we subclass CXFNonSpringJaxrsServlet with our own
SampleServlet that refers directly to our SampleApplication
+class. With the necessary imports inside the MANIFEST.MF, OSGI will set up the
correct bundle linkage at runtime and we won't get the dreaded
+ClassNotFound exception.
+
+Deployment notes
+
+By default, CXF's default OSGI bundle includes a whack of dependencies that
aren't necessary to get the core JAX-RS running. This sample
+strips away all the fluff and only includes the necessary JARs. You can check
the pom.xml accompanying this example to see many of the
+dependencies that have been excluded.
+
+To ease deployment in different OSGI environments, we take advantage of Apache
Felix's File Install bundle to use a directory-based deployment
+structure.
+
+With a few tweaks here and there, you can configure this sample to run in
different OSGI environments. By default, it works in Eclipse Equinox but
+it runs sufficiently well in Apache Felix as well.
+
+Running the sample
+------------------
+
+You can run it directly from maven using the following command
+
+ mvn exec:exec
+
+Note that when you run the sample this way, your input to the OSGI console
will not echo. No worries, it'll still be processed!
+
+If you want to run it manually, do the following
+
+ 1) mvn package
+ 2) cd
target/deliver/jax_rs_minimal_osgi-<version>-equinox/jax_rs_minimal_osgi-<version>/
+ 3) java -jar org.eclipse.osgi-3.6.2.R36x_v20110210.jar
+
+If all goes well, the Eclipse Equinox environment will start up and File
Install will install all the necessary bundles.
+
+If you visit the following URL in your favorite browser on the machine, you
should find it returns some text from SampleApplication:
+
+ http://localhost:8080/
+
+Bundles
+-------
+
+If you're using Java 6, here is a listing of the bundles that are running
inside Eclipse Equinox to make this example run successfully:
+
+id State Bundle
+0 ACTIVE org.eclipse.osgi_3.6.2.R36x_v20110210 ;
OSGI system runtime
+1 ACTIVE org.apache.felix.fileinstall_3.1.10 ;
Bundle deployment system - may be removed if you have some other way to deploy
+2 ACTIVE org.codehaus.jettison.jettison_1.3.0 ;
CXF JAX-RS dependency for JSON
+3 ACTIVE org.mortbay.jetty.util_6.1.24 ;
HTTP OSGI service dependency
+4 ACTIVE org.apache.cxf.bundle-jaxrs_2.5.0.SNAPSHOT ;
CXF JAX-RS bundle
+5 ACTIVE org.apache.neethi_3.0.1 ;
CXF JAX-RS dependency
+6 ACTIVE org.eclipse.osgi.services_3.2.100.v20100503 ;
CXF JAX-RS dependency / HTTP OSGI service dependency
+7 ACTIVE org.apache.felix.http.whiteboard_2.2.0 ;
HTTP OSGI service dependency
+8 ACTIVE org.mortbay.jetty.security_6.1.24 ;
HTTP OSGI service dependency
+9 ACTIVE org.mortbay.jetty.server_6.1.24 ;
HTTP OSGI service dependency
+10 ACTIVE org.apache.felix.http.bundle_2.2.0 ;
HTTP OSGI service dependency
+11 ACTIVE org.apache.felix.http.base_2.2.0 ;
HTTP OSGI service dependency
+12 ACTIVE org.apache.servicemix.specs.jsr311-api-1.1_1.8.0 ;
CXF JAX-RS dependency
+13 ACTIVE org.apache.felix.http.bridge_2.2.0 ;
HTTP OSGI service dependency
+14 ACTIVE minimalosgi_0.0.0 ;
Sample application
+15 ACTIVE org.apache.felix.http.api_2.2.0 ;
HTTP OSGI service dependency
+16 ACTIVE org.apache.felix.http.jetty_2.2.0 ;
HTTP OSGI service dependency
+
+If you're using Java 5, there's a few more bundles that are added to make
things run successfully
+
+id State Bundle
+17 ACTIVE
org.apache.geronimo.specs.geronimo-activation_1.1_spec_1.1.0 ; CXF JAX-RS
dependency
+18 ACTIVE org.apache.servicemix.specs.stax-api-1.0_1.9.0
; CXF JAX-RS dependency
+19 ACTIVE org.apache.servicemix.specs.activation-api-1.1_1.9.0
; CXF JAX-RS dependency
+20 ACTIVE org.apache.servicemix.specs.jaxb-api-2.2_1.9.0
; CXF JAX-RS dependency
+21 ACTIVE
org.apache.geronimo.specs.geronimo-annotation_1.0_spec_1.1.1 ; CXF JAX-RS
dependency
Added: cxf/trunk/distribution/src/main/release/samples/oauth/README.txt
URL:
http://svn.apache.org/viewvc/cxf/trunk/distribution/src/main/release/samples/oauth/README.txt?rev=1303153&view=auto
==============================================================================
--- cxf/trunk/distribution/src/main/release/samples/oauth/README.txt (added)
+++ cxf/trunk/distribution/src/main/release/samples/oauth/README.txt Tue Mar 20
21:08:46 2012
@@ -0,0 +1,63 @@
+OAuth 1.0a demo (client and server)
+========================================
+The OAuth 1.0a demo that shows protocol's flow between OAuth parties. Demo
contains two parts:
+
+ client:
+ A web application capable of making OAuth-authenticated requests.
It is a usual OAuth client,
+ not dependent on Apache CXF framework, built to test this demo
server part and for OAuth
+ educational purposes. Implementation works with any OAuth 1.0a
providers, not only inluded
+ in this demo.
+
+
+ server:
+ A web application capable of accepting OAuth-authenticated
requests. It is based on Apache
+ CXF OAuth module. It exposes OAuth endpoints and protected
resources in the form of JAX-RS
+ services. Server demo shows and explains how CXF OAuth module can
be configured to secure
+ JAX-RS services and integrated with existing web applications.
+
+Building and running the demo using maven
+---------------------------------------
+
+ client:
+ Main directory of client demo application is located in folder:
"client", in base folder
+ of this sample.
+ To start demo app use maven command:
+
+ mvn jetty:run
+
+ It will cause in starting Jetty web server and deploying client
application at host on port: 8080.
+ Port number is defined in pom.xml.
+
+ server:
+ Main directory of server demo application is located in folder:
"server", in base folder
+ of this sample.
+ To start demo app use maven command:
+
+ mvn jetty:run
+
+ It will cause in starting Jetty web server and deploying client
application at host on port: 8081.
+ Port number is defined in pom.xml.
+
+
+ Both client and server modules sepends on Spring 3, so you need to use
CXF spring3 profile.
+ You can build both client and server modules using command:
+
+ mvn clean install
+
+ and deploy war from 'target' folder in selected web container.
+
+Performing steps in the OAuth flow
+-----------------------------
+When you have successfully deployed client and server you can start with OAuth
steps:
+1. Go to OAuth server (http://localhost:8081) and login with given username
and password
+2. Provide details and register new application at the OAuth server.
+3. You have registered client application at the OAuth server, with associated
and displayed
+ client identifier, client shared-secret and callback url. You will need
those on the client side.
+4. Go to OAuth client demo (http://localhost:8080) and provide information
about the registered application.
+5. Perform usuall OAuth 1.0 flow steps
+
+
+
+Running OAuth 1.0a demo at Google App Engine
+-----------------------------
+//todo add challenges in deploying demo to GAE
