Mailing-List: contact commits-help@cxf.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cxf.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1067931 - in /cxf/trunk/rt/frontend/jaxrs/src:
 main/java/org/apache/cxf/jaxrs/ main/java/org/apache/cxf/jaxrs/client/
 main/java/org/apache/cxf/jaxrs/ext/xml/ test/java/org/apache/cxf/jaxrs/impl/
Date: Mon, 07 Feb 2011 12:18:43 -0000
To: commits@cxf.apache.org
From: sergeyb@apache.org
Message-Id: <20110207121843.AB55123889FD@eris.apache.org>

Author: sergeyb
Date: Mon Feb  7 12:18:43 2011
New Revision: 1067931

URL: http://svn.apache.org/viewvc?rev=1067931&view=rev
Log:
[JAX-RS] Adding some documentation as well as few more UriBuilder tests with 2 being disabled

Modified:
    cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/AbstractJAXRSFactoryBean.java
    cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/JAXRSServerFactoryBean.java
    cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/JAXRSClientFactoryBean.java
    cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/ServerWebApplicationException.java
    cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLSource.java
    cxf/trunk/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/impl/UriBuilderImplTest.java

Modified: cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/AbstractJAXRSFactoryBean.java
URL: http://svn.apache.org/viewvc/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/AbstractJAXRSFactoryBean.java?rev=1067931&r1=1067930&r2=1067931&view=diff
==============================================================================
--- cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/AbstractJAXRSFactoryBean.java (original)
+++ cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/AbstractJAXRSFactoryBean.java Mon Feb  7 12:18:43 2011
@@ -359,18 +359,48 @@ public class AbstractJAXRSFactoryBean ex
         factory.setUserProviders(Collections.singletonList(new DataBindingProvider(db)));
     }
     
+    /**
+     * Sets the description of root resources.
+     * Can be used to 'attach' the JAX-RS like description to the application
+     * classes without adding JAX-RS annotations.
+     *   
+     * @param resources root resource descriptions 
+     */
     public void setModelBeans(UserResource... resources) {
         setModelBeans(Arrays.asList(resources));
     }
     
+    /**
+     * Sets the description of root resources.
+     * Can be used to 'attach' the JAX-RS like description to the application
+     * classes without adding JAX-RS annotations.
+     *   
+     * @param resources root resource descriptions 
+     */
     public void setModelBeans(List<UserResource> resources) {
         serviceFactory.setUserResources(resources);
     }
     
+    /**
+     * Sets the description of root resources with the list of concrete classes.
+     * Can be used to 'attach' the JAX-RS like description to the application
+     * classes without adding JAX-RS annotations. Some models may only reference
+     * interfaces, thus providing a list of concrete classes that will be
+     * instantiated is required in such cases.
+     *   
+     * @param resources root resource descriptions.
+     * @param sClasses concrete root resource classes
+     */
     public void setModelBeansWithServiceClass(List<UserResource> resources, Class<?>... sClasses) {
         serviceFactory.setUserResourcesWithServiceClass(resources, sClasses);
     }
     
+    /**
+     * Sets a reference to the external user model, 
+     * Example: "classpath:/model/resources.xml"
+     * 
+     * @param modelRef the reference to the external model resource.
+     */
     public void setModelRef(String modelRef) {
         List<UserResource> resources = ResourceUtils.getUserResources(modelRef, getBus());
         if (resources != null) {
@@ -378,6 +408,15 @@ public class AbstractJAXRSFactoryBean ex
         }
     }
     
+    /**
+     * Sets a reference to the external user model, 
+     * Example: "classpath:/model/resources.xml".
+     * Some models may only reference interfaces, thus providing a list of 
+     * concrete classes that will be instantiated is required in such cases.
+     * 
+     * @param modelRef the reference to the external model resource.
+     * @param sClasses concrete root resource classes
+     */
     public void setModelRefWithServiceClass(String modelRef, Class<?>... sClasses) {
         List<UserResource> resources = ResourceUtils.getUserResources(modelRef, getBus());
         if (resources != null) {

Modified: cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/JAXRSServerFactoryBean.java
URL: http://svn.apache.org/viewvc/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/JAXRSServerFactoryBean.java?rev=1067931&r1=1067930&r2=1067931&view=diff
==============================================================================
--- cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/JAXRSServerFactoryBean.java (original)
+++ cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/JAXRSServerFactoryBean.java Mon Feb  7 12:18:43 2011
@@ -227,6 +227,8 @@ public class JAXRSServerFactoryBean exte
     /**
      * Sets the single resource bean. If this is set then the JAX-RS runtime 
      * will not be responsible for the life-cycle of resource classes.
+     * Please avoid setting the resource class of this bean explicitly,
+     * the runtime will determine it itself.  
      * 
      * @param bean resource instance
      */

Modified: cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/JAXRSClientFactoryBean.java
URL: http://svn.apache.org/viewvc/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/JAXRSClientFactoryBean.java?rev=1067931&r1=1067930&r2=1067931&view=diff
==============================================================================
--- cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/JAXRSClientFactoryBean.java (original)
+++ cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/JAXRSClientFactoryBean.java Mon Feb  7 12:18:43 2011
@@ -59,38 +59,88 @@ public class JAXRSClientFactoryBean exte
         
     }
     
+    /**
+     * Indicates if a single proxy or WebClient instance can be reused 
+     * by multiple threads.
+     *   
+     * @param threadSafe if true then multiple threads can invoke on
+     *        the same proxy or WebClient instance.
+     */
     public void setThreadSafe(boolean threadSafe) {
         this.threadSafe = threadSafe;
     }
     
+    /**
+     * Gets the user name
+     * @return the name
+     */
     public String getUsername() {
         return username;
     }
 
+    /**
+     * Sets the username. 
+     * Setting the username and password is a simple way to 
+     * create a Basic Authentication token.
+     * 
+     * @param username the user name
+     */
     public void setUsername(String username) {        
         this.username = username;
     }
     
+    /**
+     * Gets the password
+     * @return the password
+     */
     public String getPassword() {
         return password;
     }
 
+    /**
+     * Sets the password. 
+     * Setting the username and password is a simple way to 
+     * create a Basic Authentication token.
+     * 
+     * @param password the password
+     */
     public void setPassword(String password) {
         this.password = password;
     }
     
+    /**
+     * Indicates if the headers set by a current proxy will be inherited
+     * when a subresource proxy is created
+     * vice versa.
+     * 
+     * @param ih if set to true then the current headers will be inherited
+     */
     public void setInheritHeaders(boolean ih) {
         inheritHeaders = ih;
     }
     
+    /**
+     * Sets the resource class
+     * @param cls the resource class
+     */
     public void setResourceClass(Class cls) {
         setServiceClass(cls);
     }
     
+    /**
+     * Sets the resource class, may be called from a Spring handler 
+     * @param cls the resource class
+     */
     public void setServiceClass(Class cls) {
         serviceFactory.setResourceClass(cls);
     }
     
+    /**
+     * Sets the headers new proxy or WebClient instances will be
+     * initialized with.
+     * 
+     * @param map the headers
+     */
     public void setHeaders(Map<String, String> map) {
         headers = new MetadataMap<String, String>();
         for (Map.Entry<String, String> entry : map.entrySet()) {
@@ -103,10 +153,18 @@ public class JAXRSClientFactoryBean exte
         }
     }
     
+    /**
+     * Gets the initial headers
+     * @return the headers
+     */
     public Map getHeaders() {
         return headers;
     }
     
+    /**
+     * Creates a WebClient instance
+     * @return WebClient instance
+     */
     public WebClient createWebClient() {
         
         Service service = new JAXRSServiceImpl(getAddress(), getServiceName());
@@ -138,14 +196,32 @@ public class JAXRSClientFactoryBean exte
         }
     }
     
+    /**
+     * Creates a proxy
+     * @param cls the proxy class
+     * @param varValues optional list of values which will be used to substitute
+     *        template variables specified in the class-level JAX-RS Path annotations
+     * @return the proxy
+     */
     public <T> T create(Class<T> cls, Object... varValues) {
         return cls.cast(createWithValues(varValues));
     }
     
+    /**
+     * Create a Client instance. Proxies and WebClients are Clients.
+     * @return the client
+     */
     public Client create() { 
         return createWithValues();
     }
     
+    /**
+     * Create a Client instance. Proxies and WebClients are Clients.
+     * @param varValues optional list of values which will be used to substitute
+     *        template variables specified in the class-level JAX-RS Path annotations
+     *        
+     * @return the client
+     */
     public Client createWithValues(Object... varValues) {
         serviceFactory.setBus(getBus());
         checkResources(false);
@@ -233,6 +309,10 @@ public class JAXRSClientFactoryBean exte
         }
     }
 
+    /**
+     * Sets the initial client state, can be a thread-safe state.
+     * @param initialState the state
+     */
     public void setInitialState(ClientState initialState) {
         this.initialState = initialState;
     }

Modified: cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/ServerWebApplicationException.java
URL: http://svn.apache.org/viewvc/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/ServerWebApplicationException.java?rev=1067931&r1=1067930&r2=1067931&view=diff
==============================================================================
--- cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/ServerWebApplicationException.java (original)
+++ cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/client/ServerWebApplicationException.java Mon Feb  7 12:18:43 2011
@@ -32,7 +32,7 @@ import org.apache.cxf.helpers.IOUtils;
 import org.apache.cxf.jaxrs.impl.MetadataMap;
 
 /**
- * Utility Exception class which makes it easier to get to the status,
+ * Utility Exception class which makes it easier to get the response status,
  * headers and error message if any
  */
 public class ServerWebApplicationException extends WebApplicationException {

Modified: cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLSource.java
URL: http://svn.apache.org/viewvc/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLSource.java?rev=1067931&r1=1067930&r2=1067931&view=diff
==============================================================================
--- cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLSource.java (original)
+++ cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLSource.java Mon Feb  7 12:18:43 2011
@@ -73,6 +73,10 @@ public class XMLSource {
         stream = is;
     }
     
+    /**
+     * Allows for multiple queries against the same stream
+     * @param enable if set to true then multiple queries will be supported. 
+     */
     public void setBuffering(boolean enable) {
         buffering = enable;
         if (!stream.markSupported()) {
@@ -84,10 +88,29 @@ public class XMLSource {
         }
     }
     
+    /**
+     * Find the matching XML node and convert it into an instance of the provided class.
+     * The default JAXB MessageBodyReader is currently used in case of non-primitive types.
+     * 
+     * @param expression XPath expression
+     * @param cls class of the node
+     * @return the instance representing the matching node
+     */
     public <T> T getNode(String expression, Class<T> cls) {
         return getNode(expression, CastUtils.cast(Collections.emptyMap(), String.class, String.class), cls);
     }
     
+    /**
+     * Find the matching XML node and convert it into an instance of the provided class.
+     * The default JAXB MessageBodyReader is currently used in case of non-primitive types.
+     * 
+     * @param expression XPath expression
+     * @param namespaces the namespaces map, prefixes which are used in the XPath expression
+     *        are the keys, namespace URIs are the values; note, the prefixes do not have to match
+     *        the actual ones used in the XML instance.
+     * @param cls class of the node
+     * @return the instance representing the matching node
+     */
     public <T> T getNode(String expression, Map<String, String> namespaces, Class<T> cls) {
         Node node = (Node)evaluate(expression, namespaces, XPathConstants.NODE);
         if (node == null) {
@@ -100,10 +123,31 @@ public class XMLSource {
         }
     }
     
+    /**
+     * Find the list of matching XML nodes and convert them into
+     * an array of instances of the provided class.
+     * The default JAXB MessageBodyReader is currently used  in case of non-primitive types.
+     * 
+     * @param expression XPath expression
+     * @param cls class of the node
+     * @return the array of instances representing the matching nodes
+     */
     public <T> T[] getNodes(String expression, Class<T> cls) {
         return getNodes(expression, CastUtils.cast(Collections.emptyMap(), String.class, String.class), cls);
     }
     
+    /**
+     * Find the list of matching XML nodes and convert them into
+     * an array of instances of the provided class.
+     * The default JAXB MessageBodyReader is currently used  in case of non-primitive types.
+     * 
+     * @param expression XPath expression
+     * @param namespaces the namespaces map, prefixes which are used in the XPath expression
+     *        are the keys, namespace URIs are the values; note, the prefixes do not have to match
+     *        the actual ones used in the XML instance.
+     * @param cls class of the node
+     * @return the array of instances representing the matching nodes
+     */
     @SuppressWarnings("unchecked")
     public <T> T[] getNodes(String expression, Map<String, String> namespaces, Class<T> cls) {
         
@@ -123,15 +167,39 @@ public class XMLSource {
         return values;
     }
 
+    /**
+     * Find an attribute or text node representing
+     * an absolute or relative link and convert it to URI
+     * @param expression the XPath expression
+     * @return the link
+     */
     public URI getLink(String expression) {
         return getLink(expression, CastUtils.cast(Collections.emptyMap(), String.class, String.class));
     }
     
+    /**
+     * Find an attribute or text node representing
+     * an absolute or relative link and convert it to URI
+     * @param expression the XPath expression
+     * @param namespaces the namespaces map, prefixes which are used in the XPath expression
+     *        are the keys, namespace URIs are the values; note, the prefixes do not have to match
+     *        the actual ones used in the XML instance.
+     * @return the link
+     */
     public URI getLink(String expression, Map<String, String> namespaces) {
         String value = getValue(expression, namespaces);
         return value == null ? null : URI.create(value);
     }
     
+    /**
+     * Find attributes or text nodes representing
+     * absolute or relative links and convert them to URIs
+     * @param expression the XPath expression
+     * @param namespaces the namespaces map, prefixes which are used in the XPath expression
+     *        are the keys, namespace URIs are the values; note, the prefixes do not have to match
+     *        the actual ones used in the XML instance.
+     * @return the links
+     */
     public URI[] getLinks(String expression, Map<String, String> namespaces) {
         String[] values = getValues(expression, namespaces);
         if (values == null) {
@@ -144,20 +212,71 @@ public class XMLSource {
         return uris;
     }
     
+    /**
+     * Returns the value of the xml:base attribute, if any.
+     * This can be used to calculate an absolute URI provided 
+     * the links in the actual XML instance are relative. 
+     * 
+     * @return the xml:base value
+     */
     public URI getBaseURI() {
         Map<String, String> map = new LinkedHashMap<String, String>();
         map.put("xml", XML_NAMESPACE);
         return getLink("/*/@xml:base", map);
     }
     
+    /**
+     * Find the attribute or simple/text node
+     * @param expression the XPath expression
+     * @return the value of the matching node
+     */
     public String getValue(String expression) {
         return getValue(expression, CastUtils.cast(Collections.emptyMap(), String.class, String.class));
     }
     
+    /**
+     * Find the attribute or simple/text node
+     * @param expression the XPath expression
+     * @param namespaces the namespaces map, prefixes which are used in the XPath expression
+     *        are the keys, namespace URIs are the values; note, the prefixes do not have to match
+     *        the actual ones used in the XML instance.
+     * @return the value of the matching node
+     */
     public String getValue(String expression, Map<String, String> namespaces) {
         return getValue(expression, namespaces, String.class);
     }
     
+    /**
+     * Find the attributes or simple/text nodes
+     * @param expression the XPath expression
+     * @return the values of the matching nodes
+     */
+    public String[] getValues(String expression) {
+        return getValues(expression, CastUtils.cast(Collections.emptyMap(), String.class, String.class));
+    }
+    
+    /**
+     * Find the attributes or simple/text nodes
+     * @param expression the XPath expression
+     * @param namespaces the namespaces map, prefixes which are used in the XPath expression
+     *        are the keys, namespace URIs are the values; note, the prefixes do not have to match
+     *        the actual ones used in the XML instance.
+     * @return the values of the matching nodes
+     */
+    public String[] getValues(String expression, Map<String, String> namespaces) {
+        return getNodes(expression, namespaces, String.class);
+    }
+    
+    /**
+     * Find the attribute or simple/text node and convert the string value to the
+     * instance of the provided class, example, Integer.class. 
+     * @param expression the XPath expression
+     * @param namespaces the namespaces map, prefixes which are used in the XPath expression
+     *        are the keys, namespace URIs are the values; note, the prefixes do not have to match
+     *        the actual ones used in the XML instance.
+     * @param cls the class of the response
+     * @return the value
+     */
     public <T> T getValue(String expression, Map<String, String> namespaces, Class<T> cls) {
         Object result = evaluate(expression, namespaces, XPathConstants.STRING);
         return result == null ? null : InjectionUtils.convertStringToPrimitive(result.toString(), cls); 
@@ -175,14 +294,6 @@ public class XMLSource {
     }
     
     
-    public String[] getValues(String expression) {
-        return getValues(expression, CastUtils.cast(Collections.emptyMap(), String.class, String.class));
-    }
-    
-    public String[] getValues(String expression, Map<String, String> namespaces) {
-        return getNodes(expression, namespaces, String.class);
-    }
-    
     private static class NamespaceContextImpl implements NamespaceContext {
         
         private Map<String, String> namespaces;

Modified: cxf/trunk/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/impl/UriBuilderImplTest.java
URL: http://svn.apache.org/viewvc/cxf/trunk/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/impl/UriBuilderImplTest.java?rev=1067931&r1=1067930&r2=1067931&view=diff
==============================================================================
--- cxf/trunk/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/impl/UriBuilderImplTest.java (original)
+++ cxf/trunk/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/impl/UriBuilderImplTest.java Mon Feb  7 12:18:43 2011
@@ -34,6 +34,7 @@ import org.apache.cxf.jaxrs.resources.Ur
 import org.apache.cxf.jaxrs.utils.JAXRSUtils;
 
 import org.junit.Assert;
+import org.junit.Ignore;
 import org.junit.Test;
 
 public class UriBuilderImplTest extends Assert {
@@ -1138,4 +1139,64 @@ public class UriBuilderImplTest extends 
             .replaceQuery("name1=x&name2=%20&name3=x+y&name4=23&name5=x y").build();
         assertEquals(expected, uri.toString());        
     }
+
+    @Ignore
+    @Test
+    public void testPathParamSpaceBuild() {
+        String expected = "http://localhost:8080/name/%20";
+        URI uri = UriBuilder.fromUri("http://localhost:8080").path("name/%20").build();
+        assertEquals(expected, uri.toString());
+    }
+    
+    @Test
+    public void testPathParamSpaceBuild2() {
+        String expected = "http://localhost:8080/name/%2520";
+        URI uri = UriBuilder.fromUri("http://localhost:8080").path("name/{value}").build("%20");
+        assertEquals(expected, uri.toString());
+    }
+    
+    @Test
+    public void testPathParamSpaceBuild3() {
+        String expected = "http://localhost:8080/name%20space";
+        URI uri = UriBuilder.fromUri("http://localhost:8080").path("name space").build();
+        assertEquals(expected, uri.toString());
+    }
+    
+    @Test
+    public void testPathParamSpaceBuild4() {
+        String expected = "http://localhost:8080/name%20space";
+        URI uri = UriBuilder.fromUri("http://localhost:8080").path("name space").buildFromEncoded();
+        assertEquals(expected, uri.toString());
+    }
+    
+    @Test
+    public void testPathParamSpaceBuildEncoded() {
+        String expected = "http://localhost:8080/name/%20";
+        URI uri = UriBuilder.fromUri("http://localhost:8080").path("name/%20").buildFromEncoded();
+        assertEquals(expected, uri.toString());
+    }
+    
+    @Test
+    public void testPathParamSpaceBuildEncoded2() {
+        String expected = "http://localhost:8080/name/%20";
+        URI uri = UriBuilder.fromUri("http://localhost:8080").path("name/{value}").buildFromEncoded("%20");
+        assertEquals(expected, uri.toString());
+    }
+    
+    @Test
+    public void testQueryParamSpaceBuild() {
+        String expected = "http://localhost:8080?name=%20";
+        URI uri = UriBuilder.fromUri("http://localhost:8080").queryParam("name", "%20").build();
+        assertEquals(expected, uri.toString());
+    }
+    
+    @Ignore
+    @Test
+    public void testQueryParamSpaceBuild2() {
+        String expected = "http://localhost:8080?name=%2520";
+        URI uri = UriBuilder.fromUri("http://localhost:8080").queryParam("name", "{value}").build("%20");
+        assertEquals(expected, uri.toString());
+    }
+    
+    
 }