Package org.apache.juneau.rest.client

Class RestClient.Builder

java.lang.Object
org.apache.juneau.Context.Builder
org.apache.juneau.BeanContextable.Builder
org.apache.juneau.rest.client.RestClient.Builder
Direct Known Subclasses:
MockRestClient.Builder
Enclosing class:
RestClient
public static class RestClient.Builder extends BeanContextable.Builder
Builder class.

  • Constructor Details

    • Builder

      protected Builder()
      Constructor.

  • Method Details

    • accept

      public RestClient.Builder accept(String value)
      Appends an Accept header on this request.

      This is a shortcut for calling headerData().append(Accept.of(value)).

      Parameters:
      value - The new header value.
      Can be null (no Accept header will be added).
      Returns:
      This object.
      See Also:

    • acceptCharset

      public RestClient.Builder acceptCharset(String value)
      Sets the value for the Accept-Charset request header on all requests.

      This is a shortcut for calling headerData().append(AcceptCharset.of(value)).

      Parameters:
      value - The new header value.
      Can be null (no Accept-Charset header will be added).
      Returns:
      This object.
      See Also:

    • addBeanTypes

      public RestClient.Builder addBeanTypes()
      Serializer configuration property:  Add "_type" properties when needed.

      When enabled, "_type" properties will be added to beans if their type cannot be inferred through reflection.

      This is used to recreate the correct objects during parsing if the object types cannot be inferred.
      For example, when serializing a Map<String,Object> field where the bean class cannot be determined from the type of the values.

      Note the differences between the following settings:

      Example:

      // Create a JSON client that adds _type to nodes in the request body. RestClient client = RestClient .create() .json() .addBeanTypes() .build(); // Our map of beans to serialize. @Bean(typeName="mybean") public class MyBean { public String foo = "bar"; } AMap map = AMap.of("foo", new MyBean()); // Request body will contain: {"foo":{"_type":"mybean","foo":"bar"}} client .post("http://localhost:10000/foo", map) .run();

      See Also:
      Returns:
      This object.

    • addInterceptorFirst

      public RestClient.Builder addInterceptorFirst(HttpRequestInterceptor itcp)
      Adds this protocol interceptor to the head of the protocol processing list.
      Notes:
      Parameters:
      itcp - New property value.
      Cannot be null.
      Returns:
      This object.
      See Also:

    • addInterceptorFirst

      public RestClient.Builder addInterceptorFirst(HttpResponseInterceptor itcp)
      Adds this protocol interceptor to the head of the protocol processing list.
      Notes:
      Parameters:
      itcp - New property value.
      Cannot be null.
      Returns:
      This object.
      See Also:

    • addInterceptorLast

      public RestClient.Builder addInterceptorLast(HttpRequestInterceptor itcp)
      Adds this protocol interceptor to the tail of the protocol processing list.
      Notes:
      Parameters:
      itcp - New property value.
      Cannot be null.
      Returns:
      This object.
      See Also:

    • addInterceptorLast

      public RestClient.Builder addInterceptorLast(HttpResponseInterceptor itcp)
      Adds this protocol interceptor to the tail of the protocol processing list.
      Notes:
      Parameters:
      itcp - New property value.
      Cannot be null.
      Returns:
      This object.
      See Also:

    • addRootType

      public RestClient.Builder addRootType()
      Serializer configuration property:  Add type attribute to root nodes.

      When enabled, "_type" properties will be added to top-level beans.

      When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level type information that might normally be included to determine the data type will not be serialized.

      For example, when serializing a top-level POJO with a @Bean(typeName) value, a '_type' attribute will only be added when this setting is enabled.

      Note the differences between the following settings:

      Example:

      // Create a JSON client that adds _type to root node. RestClient client = RestClient .create() .json() .addRootType() .build(); // Our bean to serialize. @Bean(typeName="mybean") public class MyBean { public String foo = "bar"; } // Request body will contain: {"_type":"mybean","foo":"bar"} client .post("http://localhost:10000/foo", new MyBean()) .run();

      See Also:
      Returns:
      This object.

    • annotations

      public RestClient.Builder annotations(Annotation... values)
      Description copied from class: Context.Builder
      Defines annotations to apply to specific classes and methods.

      Allows you to dynamically apply Juneau annotations typically applied directly to classes and methods. Useful in cases where you want to use the functionality of the annotation on beans and bean properties but do not have access to the code to do so.

      As a rule, any Juneau annotation with an on() method can be used with this setting.

      The following example shows the equivalent methods for applying the @Bean annotation:

      // Class with explicit annotation. @Bean(properties="street,city,state") public class A {...} // Class with annotation applied via @BeanConfig public class B {...} // Java REST method with @BeanConfig annotation. @RestGet(...) @Bean(on="B", properties="street,city,state") public void doFoo() {...}

      In general, the underlying framework uses this method when it finds dynamically applied annotations on config annotations. However, concrete implementations of annotations are also provided that can be passed directly into builder classes like so:

      // Create a concrete @Bean annotation. Bean annotation = BeanAnnotation.create(B.class).properties("street,city,state").build(); // Apply it to a serializer. WriterSerializer serializer = JsonSerializer.create().annotations(annotation).build(); // Serialize a bean with the dynamically applied annotation. String json = serializer.serialize(new B());

      The following is the list of annotations builders provided that can be constructed and passed into the builder class:

      The syntax for the on() pattern match parameter depends on whether it applies to a class, method, field, or constructor. The valid pattern matches are:

      • Classes:
        • Fully qualified:
          • "com.foo.MyClass"
        • Fully qualified inner class:
          • "com.foo.MyClass$Inner1$Inner2"
        • Simple:
          • "MyClass"
        • Simple inner:
          • "MyClass$Inner1$Inner2"
          • "Inner1$Inner2"
          • "Inner2"
      • Methods:
        • Fully qualified with args:
          • "com.foo.MyClass.myMethod(String,int)"
          • "com.foo.MyClass.myMethod(java.lang.String,int)"
          • "com.foo.MyClass.myMethod()"
        • Fully qualified:
          • "com.foo.MyClass.myMethod"
        • Simple with args:
          • "MyClass.myMethod(String,int)"
          • "MyClass.myMethod(java.lang.String,int)"
          • "MyClass.myMethod()"
        • Simple:
          • "MyClass.myMethod"
        • Simple inner class:
          • "MyClass$Inner1$Inner2.myMethod"
          • "Inner1$Inner2.myMethod"
          • "Inner2.myMethod"
      • Fields:
        • Fully qualified:
          • "com.foo.MyClass.myField"
        • Simple:
          • "MyClass.myField"
        • Simple inner class:
          • "MyClass$Inner1$Inner2.myField"
          • "Inner1$Inner2.myField"
          • "Inner2.myField"
      • Constructors:
        • Fully qualified with args:
          • "com.foo.MyClass(String,int)"
          • "com.foo.MyClass(java.lang.String,int)"
          • "com.foo.MyClass()"
        • Simple with args:
          • "MyClass(String,int)"
          • "MyClass(java.lang.String,int)"
          • "MyClass()"
        • Simple inner class:
          • "MyClass$Inner1$Inner2()"
          • "Inner1$Inner2()"
          • "Inner2()"
      • A comma-delimited list of anything on this list.
      See Also:
      Overrides:
      annotations in class BeanContextable.Builder
      Parameters:
      values - The annotations to register with the context.
      Cannot contain null values.
      Returns:
      This object.

    • apply

      public RestClient.Builder apply(AnnotationWorkList work)
      Description copied from class: Context.Builder
      Applies a set of applied to this builder.

      An AnnotationWork consists of a single pair of AnnotationInfo that represents an annotation instance, and AnnotationApplier which represents the code used to apply the values in that annotation to a specific builder.

      Example:

      // A class annotated with a config annotation. @BeanConfig(sortProperties="$S{sortProperties,false}") public class MyClass {...} // Find all annotations that themselves are annotated with @ContextPropertiesApply. Stream<AnnotationInfo<?>> annotations = ClassInfo.of(MyClass.class).getAnnotations().stream().filter(CONTEXT_APPLY_FILTER); VarResolverSession vrs = VarResolver.DEFAULT.createSession(); AnnotationWorkList work = AnnotationWorkList.of(vrs, annotations); // Apply any settings found on the annotations. WriterSerializer serializer = JsonSerializer .create() .apply(work) .build();

      Overrides:
      apply in class BeanContextable.Builder
      Parameters:
      work - The list of annotations and appliers to apply to this builder.
      Cannot be null.
      Returns:
      This object.

    • applyAnnotations

      public RestClient.Builder applyAnnotations(Class<?>... from)
      Description copied from class: Context.Builder
      Same as Context.Builder.applyAnnotations(Object...) but explicitly specifies a class varargs to avoid compilation warnings.
      Overrides:
      applyAnnotations in class BeanContextable.Builder
      Parameters:
      from - The classes or methods on which the annotations are defined.
      Cannot contain null values.
      Returns:
      This object.

    • applyAnnotations

      public RestClient.Builder applyAnnotations(Object... from)
      Description copied from class: Context.Builder
      Applies any of the various @XConfig annotations on the specified classes or methods to this context.

      Any annotations found that themselves are annotated with ContextApply will be resolved and applied as properties to this builder. These annotations include:

      Annotations on classes are appended in the following order:

      1. On the package of this class.
      2. On interfaces ordered parent-to-child.
      3. On parent classes ordered parent-to-child.
      4. On this class.

      Annotations on methods are appended in the following order:

      1. On the package of the method class.
      2. On interfaces ordered parent-to-child.
      3. On parent classes ordered parent-to-child.
      4. On the method class.
      5. On this method and matching methods ordered parent-to-child.

      The default var resolver VarResolver.DEFAULT is used to resolve any variables in annotation field values.

      Example:

      // A class annotated with a config annotation. @BeanConfig(sortProperties="$S{sortProperties,false}") public class MyClass {...} // Apply any settings found on the annotations. WriterSerializer serializer = JsonSerializer .create() .applyAnnotations(MyClass.class) .build(); // A method annotated with a config annotation. public class MyClass { @BeanConfig(sortProperties="$S{sortProperties,false}") public void myMethod() {...} } // Apply any settings found on the annotations. WriterSerializer serializer = JsonSerializer .create() .applyAnnotations(MyClass.class.getMethod("myMethod")) .build();

      Overrides:
      applyAnnotations in class BeanContextable.Builder
      Parameters:
      from - The classes or methods on which the annotations are defined. Can be any of the following types:
      Returns:
      This object.

    • backoffManager

      public RestClient.Builder backoffManager(BackoffManager backoffManager)
      Assigns BackoffManager instance.
      Parameters:
      backoffManager - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • basicAuth

      public RestClient.Builder basicAuth(String host, int port, String user, String pw)
      Set up this client to use BASIC auth.
      Example:

      // Construct a client that uses BASIC authentication. RestClient client = RestClient .create() .basicAuth("http://localhost", 80, "me", "mypassword") .build();

      Parameters:
      host - The auth scope hostname.
      Can be null (will use "*" as the hostname).
      port - The auth scope port.
      user - The username.
      Can be null (will use empty string).
      pw - The password.
      Can be null (will use empty string).
      Returns:
      This object.

    • beanClassVisibility

      public RestClient.Builder beanClassVisibility(Visibility value)
      Description copied from class: BeanContextable.Builder
      Minimum bean class visibility.

      Classes are not considered beans unless they meet the minimum visibility requirements. For example, if the visibility is PUBLIC and the bean class is protected, then the class will not be interpreted as a bean class and be serialized as a string. Use this setting to reduce the visibility requirement.

      Example:

      // A bean with a protected class and one field. protected class MyBean { public String foo = "bar"; } // Create a serializer that's capable of serializing the class. WriterSerializer serializer = JsonSerializer .create() .beanClassVisibility(PROTECTED) .build(); // Produces: {"foo","bar"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Bean annotation can be used on a non-public bean class to override this setting.
      • The @BeanIgnore annotation can also be used on a public bean class to ignore it as a bean.
      See Also:
      Overrides:
      beanClassVisibility in class BeanContextable.Builder
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC.
      Cannot be null.
      Returns:
      This object.

    • beanConstructorVisibility

      public RestClient.Builder beanConstructorVisibility(Visibility value)
      Description copied from class: BeanContextable.Builder
      Minimum bean constructor visibility.

      Only look for constructors with the specified minimum visibility.

      This setting affects the logic for finding no-arg constructors for bean. Normally, only public no-arg constructors are used. Use this setting if you want to reduce the visibility requirement.

      Example:

      // A bean with a protected constructor and one field. public class MyBean { public String foo; protected MyBean() {} } // Create a parser capable of calling the protected constructor. ReaderParser parser = ReaderParser .create() .beanConstructorVisibility(PROTECTED) .build(); // Use it. MyBean bean = parser.parse("{foo:'bar'}", MyBean.class);

      Notes:
      • The @Beanc annotation can also be used to expose a non-public constructor.
      • The @BeanIgnore annotation can also be used on a public bean constructor to ignore it.
      See Also:
      Overrides:
      beanConstructorVisibility in class BeanContextable.Builder
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC.
      Cannot be null.
      Returns:
      This object.

    • beanContext

      public RestClient.Builder beanContext(BeanContext value)
      Description copied from class: BeanContextable.Builder
      Specifies an already-instantiated bean context to use.

      Provides an optimization for cases where serializers and parsers can use an existing bean context without having to go through beanContext.copy().build(). An example is BeanContext.getBeanToStringSerializer().

      Overrides:
      beanContext in class BeanContextable.Builder
      Parameters:
      value - The bean context to use.
      Cannot be null.
      Returns:
      This object.

    • beanContext

      public RestClient.Builder beanContext(BeanContext.Builder value)
      Description copied from class: BeanContextable.Builder
      Overrides the bean context builder.

      Used when sharing bean context builders across multiple context objects. For example, JsonSchemaGenerator.Builder uses this to apply common bean settings with the JSON serializer and parser.

      Overrides:
      beanContext in class BeanContextable.Builder
      Parameters:
      value - The new value for this setting.
      Cannot be null.
      Returns:
      This object.

    • beanDictionary

      public RestClient.Builder beanDictionary(Class<?>... values)
      Description copied from class: BeanContextable.Builder
      Bean dictionary.

      The list of classes that make up the bean dictionary in this bean context.

      Values are prepended to the list so that later calls can override classes of earlier calls.

      A dictionary is a name/class mapping used to find class types during parsing when they cannot be inferred through reflection. The names are defined through the @Bean(typeName) annotation defined on the bean class. For example, if a class Foo has a type-name of "myfoo", then it would end up serialized as "{_type:'myfoo',...}" in JSON or "<myfoo>...</myfoo>" in XML.

      This setting tells the parsers which classes to look for when resolving "_type" attributes.

      Values can consist of any of the following types:

      • Any bean class that specifies a value for @Bean(typeName).
      • Any subclass of BeanDictionaryList containing a collection of bean classes with type name annotations.
      • Any subclass of BeanDictionaryMap containing a mapping of type names to classes without type name annotations.
      • Any array or collection of the objects above.
      Example:

      // POJOs with @Bean(name) annotations. @Bean(typeName="foo") public class Foo {...} @Bean(typeName="bar") public class Bar {...} // Create a parser and tell it which classes to try to resolve. ReaderParser parser = JsonParser .create() .dictionary(Foo.class, Bar.class) .addBeanTypes() .build(); // A bean with a field with an indeterminate type. public class MyBean { public Object mySimpleField; } // Parse bean. MyBean bean = parser.parse("{mySimpleField:{_type:'foo',...}}", MyBean.class);

      Another option is to use the Bean.dictionary() annotation on the POJO class itself:

      // Instead of by parser, define a bean dictionary on a class through an annotation. // This applies to all properties on this class and all subclasses. @Bean(dictionary={Foo.class,Bar.class}) public class MyBean { public Object mySimpleField; // May contain Foo or Bar object. public Map<String,Object> myMapField; // May contain Foo or Bar objects. }

      A typical usage is to allow for HTML documents to be parsed back into HTML beans:

      // Use the predefined HTML5 bean dictionary which is a BeanDictionaryList. ReaderParser parser = HtmlParser .create() .dictionary(HtmlBeanDictionary.class) .build(); // Parse an HTML body into HTML beans. Body body = parser.parse("<body><ul><li>foo</li><li>bar</li></ul>", Body.class);

      See Also:
      Overrides:
      beanDictionary in class BeanContextable.Builder
      Parameters:
      values - The values to add to this setting.
      Cannot contain null values.
      Returns:
      This object.

    • beanFieldVisibility

      public RestClient.Builder beanFieldVisibility(Visibility value)
      Description copied from class: BeanContextable.Builder
      Minimum bean field visibility.

      Only look for bean fields with the specified minimum visibility.

      This affects which fields on a bean class are considered bean properties. Normally only public fields are considered. Use this setting if you want to reduce the visibility requirement.

      Example:

      // A bean with a protected field. public class MyBean { protected String foo = "bar"; } // Create a serializer that recognizes the protected field. WriterSerializer serializer = JsonSerializer .create() .beanFieldVisibility(PROTECTED) .build(); // Produces: {"foo":"bar"} String json = serializer.serialize(new MyBean());

      Bean fields can be ignored as properties entirely by setting the value to Visibility.NONE

      // Disable using fields as properties entirely. WriterSerializer serializer = JsonSerializer .create() .beanFieldVisibility(NONE) .build();

      Notes:
      • The @Beanp annotation can also be used to expose a non-public field.
      • The @BeanIgnore annotation can also be used on a public bean field to ignore it as a bean property.
      See Also:
      Overrides:
      beanFieldVisibility in class BeanContextable.Builder
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC.
      Cannot be null.
      Returns:
      This object.

    • beanInterceptor

      public RestClient.Builder beanInterceptor(Class<?> on, Class<? extends BeanInterceptor<?>> value)
      Description copied from class: BeanContextable.Builder
      Bean interceptor.

      Bean interceptors can be used to intercept calls to getters and setters and alter their values in transit.

      Example:

      // Interceptor that strips out sensitive information. public class AddressInterceptor extends BeanInterceptor<Address> { public Object readProperty(Address bean, String name, Object value) { if ("taxInfo".equals(name)) return "redacted"; return value; } public Object writeProperty(Address bean, String name, Object value) { if ("taxInfo".equals(name) && "redacted".equals(value)) return TaxInfoUtils.lookup(bean.getStreet(), bean.getCity(), bean.getState()); return value; } } // Our bean class. public class Address { public String getTaxInfo() {...} public void setTaxInfo(String value) {...} } // Register filter on serializer or parser. WriterSerializer serializer = JsonSerializer .create() .beanInterceptor(Address.class, AddressInterceptor.class) .build(); // Produces: {"taxInfo":"redacted"} String json = serializer.serialize(new Address());

      See Also:
      Overrides:
      beanInterceptor in class BeanContextable.Builder
      Parameters:
      on - The bean that the filter applies to.
      Cannot be null.
      value - The new value for this setting.
      Cannot be null.
      Returns:
      This object.

    • beanMethodVisibility

      public RestClient.Builder beanMethodVisibility(Visibility value)
      Description copied from class: BeanContextable.Builder
      Minimum bean method visibility.

      Only look for bean methods with the specified minimum visibility.

      This affects which methods are detected as getters and setters on a bean class. Normally only public getters and setters are considered. Use this setting if you want to reduce the visibility requirement.

      Example:

      // A bean with a protected getter. public class MyBean { public String getFoo() { return "foo"; } protected String getBar() { return "bar"; } } // Create a serializer that looks for protected getters and setters. WriterSerializer serializer = JsonSerializer .create() .beanMethodVisibility(PROTECTED) .build(); // Produces: {"foo":"foo","bar":"bar"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Beanp annotation can also be used to expose a non-public method.
      • The @BeanIgnore annotation can also be used on a public bean getter/setter to ignore it as a bean property.
      See Also:
      Overrides:
      beanMethodVisibility in class BeanContextable.Builder
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC
      Cannot be null.
      Returns:
      This object.

    • beanProperties

      public RestClient.Builder beanProperties(Class<?> beanClass, String properties)
      Description copied from class: BeanContextable.Builder
      Bean property includes.

      Specifies the set and order of names of properties associated with the bean class.

      For example, beanProperties(MyBean.class, "foo,bar") means only serialize the foo and bar properties on the specified bean. Likewise, parsing will ignore any bean properties not specified and either throw an exception or silently ignore them depending on whether BeanContextable.Builder.ignoreUnknownBeanProperties() has been called.

      This value is entirely optional if you simply want to expose all the getters and public fields on a class as bean properties. However, it's useful if you want certain getters to be ignored or you want the properties to be serialized in a particular order. Note that on IBM JREs, the property order is the same as the order in the source code, whereas on Oracle JREs, the order is entirely random.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that includes only the 'foo' and 'bar' properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanProperties(MyBean.class, "foo,bar") .build(); // Produces: {"foo":"foo","bar":"bar"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClass).properties(properties).build());

      See Also:
      Overrides:
      beanProperties in class BeanContextable.Builder
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Cannot be null.
      Returns:
      This object.

    • beanProperties

      public RestClient.Builder beanProperties(Map<String,Object> values)
      Description copied from class: BeanContextable.Builder
      Bean property includes.

      Specifies the set and order of names of properties associated with bean classes.

      For example, beanProperties(AMap.of("MyBean", "foo,bar")) means only serialize the foo and bar properties on the specified bean. Likewise, parsing will ignore any bean properties not specified and either throw an exception or silently ignore them depending on whether BeanContextable.Builder.ignoreUnknownBeanProperties() has been called.

      This value is entirely optional if you simply want to expose all the getters and public fields on a class as bean properties. However, it's useful if you want certain getters to be ignored or you want the properties to be serialized in a particular order. Note that on IBM JREs, the property order is the same as the order in the source code, whereas on Oracle JREs, the order is entirely random.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that includes only the 'foo' and 'bar' properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanProperties(AMap.of("MyBean", "foo,bar")) .build(); // Produces: {"foo":"foo","bar":"bar"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code for each entry:

      builder.annotations(BeanAnnotation.create(key).properties(value.toString()).build());

      See Also:
      Overrides:
      beanProperties in class BeanContextable.Builder
      Parameters:
      values - The values to add to this builder.
      Keys are bean class names which can be a simple name, fully-qualified name, or "*" for all beans.
      Values are comma-delimited lists of property names. Non-String objects are first converted to Strings.
      Cannot be null.
      Returns:
      This object.

    • beanProperties

      public RestClient.Builder beanProperties(String beanClassName, String properties)
      Description copied from class: BeanContextable.Builder
      Bean property includes.

      Specifies the set and order of names of properties associated with the bean class.

      For example, beanProperties("MyBean", "foo,bar") means only serialize the foo and bar properties on the specified bean. Likewise, parsing will ignore any bean properties not specified and either throw an exception or silently ignore them depending on whether BeanContextable.Builder.ignoreUnknownBeanProperties() has been called.

      This value is entirely optional if you simply want to expose all the getters and public fields on a class as bean properties. However, it's useful if you want certain getters to be ignored or you want the properties to be serialized in a particular order. Note that on IBM JREs, the property order is the same as the order in the source code, whereas on Oracle JREs, the order is entirely random.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that includes only the 'foo' and 'bar' properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanProperties("MyBean", "foo,bar") .build(); // Produces: {"foo":"foo","bar":"bar"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClassName).properties(properties).build());

      See Also:
      Overrides:
      beanProperties in class BeanContextable.Builder
      Parameters:
      beanClassName - The bean class name.
      Can be a simple name, fully-qualified name, or "*" for all beans.
      Cannot be null.
      properties - Comma-delimited list of property names.
      Cannot be null.
      Returns:
      This object.

    • beanPropertiesExcludes

      public RestClient.Builder beanPropertiesExcludes(Class<?> beanClass, String properties)
      Description copied from class: BeanContextable.Builder
      Bean property excludes.

      Specifies to exclude the specified list of properties for the specified bean class.

      Same as BeanContextable.Builder.beanProperties(Class, String) except you specify a list of bean property names that you want to exclude from serialization.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that excludes the "bar" and "baz" properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesExcludes(MyBean.class, "bar,baz") .build(); // Produces: {"foo":"foo"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClass).excludeProperties(properties).build());

      See Also:
      Overrides:
      beanPropertiesExcludes in class BeanContextable.Builder
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Cannot be null.
      Returns:
      This object.

    • beanPropertiesExcludes

      public RestClient.Builder beanPropertiesExcludes(Map<String,Object> values)
      Description copied from class: BeanContextable.Builder
      Bean property excludes.

      Specifies to exclude the specified list of properties for the specified bean classes.

      Same as BeanContextable.Builder.beanProperties(Map) except you specify a list of bean property names that you want to exclude from serialization.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that excludes the "bar" and "baz" properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesExcludes(AMap.of("MyBean", "bar,baz")) .build(); // Produces: {"foo":"foo"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code for each entry:

      builder.annotations(BeanAnnotation.create(key).excludeProperties(value.toString()).build());

      See Also:
      Overrides:
      beanPropertiesExcludes in class BeanContextable.Builder
      Parameters:
      values - The values to add to this builder.
      Keys are bean class names which can be a simple name, fully-qualified name, or "*" for all beans.
      Values are comma-delimited lists of property names. Non-String objects are first converted to Strings.
      Cannot be null.
      Returns:
      This object.

    • beanPropertiesExcludes

      public RestClient.Builder beanPropertiesExcludes(String beanClassName, String properties)
      Description copied from class: BeanContextable.Builder
      Bean property excludes.

      Specifies to exclude the specified list of properties for the specified bean class.

      Same as BeanContextable.Builder.beanPropertiesExcludes(String, String) except you specify a list of bean property names that you want to exclude from serialization.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that excludes the "bar" and "baz" properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesExcludes("MyBean", "bar,baz") .build(); // Produces: {"foo":"foo"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClassName).excludeProperties(properties).build());

      See Also:
      Overrides:
      beanPropertiesExcludes in class BeanContextable.Builder
      Parameters:
      beanClassName - The bean class name.
      Can be a simple name, fully-qualified name, or "*" for all bean classes.
      Cannot be null.
      properties - Comma-delimited list of property names.
      Cannot be null.
      Returns:
      This object.

    • beanPropertiesReadOnly

      public RestClient.Builder beanPropertiesReadOnly(Class<?> beanClass, String properties)
      Description copied from class: BeanContextable.Builder
      Read-only bean properties.

      Specifies one or more properties on a bean that are read-only despite having valid getters. Serializers will serialize such properties as usual, but parsers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with read-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesReadOnly(MyBean.class, "bar,baz") .build(); // All 3 properties will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with read-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesReadOnly(MyBean.class, "bar,baz") .ignoreUnknownBeanProperties() .build(); // Parser ignores bar and baz properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClass).readOnlyProperties(properties).build());

      See Also:
      Overrides:
      beanPropertiesReadOnly in class BeanContextable.Builder
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Cannot be null.
      Returns:
      This object.

    • beanPropertiesReadOnly

      public RestClient.Builder beanPropertiesReadOnly(Map<String,Object> values)
      Description copied from class: BeanContextable.Builder
      Read-only bean properties.

      Specifies one or more properties on beans that are read-only despite having valid getters. Serializers will serialize such properties as usual, but parsers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with read-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesReadOnly(AMap.of("MyBean", "bar,baz")) .build(); // All 3 properties will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with read-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesReadOnly(AMap.of("MyBean", "bar,baz")) .ignoreUnknownBeanProperties() .build(); // Parser ignores bar and baz properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code for each entry:

      builder.annotations(BeanAnnotation.create(key).readOnlyProperties(value.toString()).build());

      See Also:
      Overrides:
      beanPropertiesReadOnly in class BeanContextable.Builder
      Parameters:
      values - The values to add to this builder.
      Keys are bean class names which can be a simple name, fully-qualified name, or "*" for all beans.
      Values are comma-delimited lists of property names. Non-String objects are first converted to Strings.
      Cannot be null.
      Returns:
      This object.

    • beanPropertiesReadOnly

      public RestClient.Builder beanPropertiesReadOnly(String beanClassName, String properties)
      Description copied from class: BeanContextable.Builder
      Read-only bean properties.

      Specifies one or more properties on a bean that are read-only despite having valid getters. Serializers will serialize such properties as usual, but parsers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with read-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesReadOnly("MyBean", "bar,baz") .build(); // All 3 properties will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with read-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesReadOnly("MyBean", "bar,baz") .ignoreUnknownBeanProperties() .build(); // Parser ignores bar and baz properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClassName).readOnlyProperties(properties).build());

      See Also:
      Overrides:
      beanPropertiesReadOnly in class BeanContextable.Builder
      Parameters:
      beanClassName - The bean class name.
      Can be a simple name, fully-qualified name, or "*" for all bean classes.
      Cannot be null.
      properties - Comma-delimited list of property names.
      Cannot be null.
      Returns:
      This object.

    • beanPropertiesWriteOnly

      public RestClient.Builder beanPropertiesWriteOnly(Class<?> beanClass, String properties)
      Description copied from class: BeanContextable.Builder
      Write-only bean properties.

      Specifies one or more properties on a bean that are write-only despite having valid setters. Parsers will parse such properties as usual, but serializers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with write-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesWriteOnly(MyBean.class, "bar,baz") .build(); // Only foo will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with write-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesWriteOnly(MyBean.class, "bar,baz") .build(); // Parser parses all 3 properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClass).writeOnlyProperties(properties).build());

      See Also:
      Overrides:
      beanPropertiesWriteOnly in class BeanContextable.Builder
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Cannot be null.
      Returns:
      This object.

    • beanPropertiesWriteOnly

      public RestClient.Builder beanPropertiesWriteOnly(Map<String,Object> values)
      Description copied from class: BeanContextable.Builder
      Write-only bean properties.

      Specifies one or more properties on a bean that are write-only despite having valid setters. Parsers will parse such properties as usual, but serializers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with write-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesWriteOnly(AMap.of("MyBean", "bar,baz")) .build(); // Only foo will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with write-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesWriteOnly(AMap.of("MyBean", "bar,baz")) .build(); // Parser parses all 3 properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code for each entry:

      builder.annotations(BeanAnnotation.create(key).writeOnlyProperties(value.toString()).build());

      See Also:
      Overrides:
      beanPropertiesWriteOnly in class BeanContextable.Builder
      Parameters:
      values - The values to add to this builder.
      Keys are bean class names which can be a simple name, fully-qualified name, or "*" for all beans.
      Values are comma-delimited lists of property names. Non-String objects are first converted to Strings.
      Cannot be null.
      Returns:
      This object.

    • beanPropertiesWriteOnly

      public RestClient.Builder beanPropertiesWriteOnly(String beanClassName, String properties)
      Description copied from class: BeanContextable.Builder
      Write-only bean properties.

      Specifies one or more properties on a bean that are write-only despite having valid setters. Parsers will parse such properties as usual, but serializers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with write-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesWriteOnly("MyBean", "bar,baz") .build(); // Only foo will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with write-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesWriteOnly("MyBean", "bar,baz") .build(); // Parser parses all 3 properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClassName).writeOnlyProperties(properties).build());

      See Also:
      Overrides:
      beanPropertiesWriteOnly in class BeanContextable.Builder
      Parameters:
      beanClassName - The bean class name.
      Can be a simple name, fully-qualified name, or "*" for all bean classes.
      Cannot be null.
      properties - Comma-delimited list of property names.
      Cannot be null.
      Returns:
      This object.

    • beansRequireDefaultConstructor

      public RestClient.Builder beansRequireDefaultConstructor()
      Description copied from class: BeanContextable.Builder
      Beans require no-arg constructors.

      When enabled, a Java class must implement a default no-arg constructor to be considered a bean. Otherwise, the bean will be serialized as a string using the Object.toString() method.

      Example:

      // A bean without a no-arg constructor. public class MyBean { // A property method. public String foo = "bar"; // A no-arg constructor public MyBean(String foo) { this.foo = foo; } @Override public String toString() { return "bar"; } } // Create a serializer that ignores beans without default constructors. WriterSerializer serializer = JsonSerializer .create() .beansRequireDefaultConstructor() .build(); // Produces: "bar" String json = serializer.serialize(new MyBean());

      Notes:
      • The @Bean annotation can be used on a bean class to override this setting.
      • The @BeanIgnore annotation can also be used on a class to ignore it as a bean.
      See Also:
      Overrides:
      beansRequireDefaultConstructor in class BeanContextable.Builder
      Returns:
      This object.

    • beansRequireSerializable

      public RestClient.Builder beansRequireSerializable()
      Description copied from class: BeanContextable.Builder
      Beans require Serializable interface.

      When enabled, a Java class must implement the Serializable interface to be considered a bean. Otherwise, the bean will be serialized as a string using the Object.toString() method.

      Example:

      // A bean without a Serializable interface. public class MyBean { // A property method. public String foo = "bar"; @Override public String toString() { return "bar"; } } // Create a serializer that ignores beans not implementing Serializable. WriterSerializer serializer = JsonSerializer .create() .beansRequireSerializable() .build(); // Produces: "bar" String json = serializer.serialize(new MyBean());

      Notes:
      • The @Bean annotation can be used on a bean class to override this setting.
      • The @BeanIgnore annotation can also be used on a class to ignore it as a bean.
      See Also:
      Overrides:
      beansRequireSerializable in class BeanContextable.Builder
      Returns:
      This object.

    • beansRequireSettersForGetters

      public RestClient.Builder beansRequireSettersForGetters()
      Description copied from class: BeanContextable.Builder
      Beans require setters for getters.

      When enabled, ignore read-only properties (properties with getters but not setters).

      Example:

      // A bean without a Serializable interface. public class MyBean { // A read/write property. public String getFoo() { return "foo"; } public void setFoo(String foo) { ... } // A read-only property. public String getBar() { return "bar"; } } // Create a serializer that ignores bean properties without setters. WriterSerializer serializer = JsonSerializer .create() .beansRequireSettersForGetters() .build(); // Produces: {"foo":"foo"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Beanp annotation can be used on the getter to override this setting.
      • The @BeanIgnore annotation can also be used on getters to ignore them as bean properties.
      See Also:
      Overrides:
      beansRequireSettersForGetters in class BeanContextable.Builder
      Returns:
      This object.

    • build

      public RestClient build()
      Description copied from class: Context.Builder
      Build the object.
      Overrides:
      build in class Context.Builder
      Returns:
      The built object.

    • cache

      public RestClient.Builder cache(Cache<HashKey,? extends Context> value)
      Description copied from class: Context.Builder
      Specifies a cache to use for hashkey-based caching.

      When a cache is specified, contexts with the same hash key will be reused from the cache instead of creating new instances. This improves performance when building multiple contexts with identical configurations.

      If null is specified, caching is disabled and each call to Context.Builder.build() will create a new context instance.

      Overrides:
      cache in class BeanContextable.Builder
      Parameters:
      value - The cache.
      Can be null (disables caching, each build creates a new instance).
      Returns:
      This object.

    • callHandler

      public final BeanCreator<RestCallHandler> callHandler()
      Returns the creator for the rest call handler.

      Allows you to provide a custom handler for making HTTP calls.

      Example:

      // Create a client that handles processing of requests using a custom handler. public class MyRestCallHandler implements RestCallHandler { @Override public HttpResponse run(HttpHost target, HttpRequest request, HttpContext context) throws IOException { // Custom handle requests. } } RestClient client = RestClient .create() .callHandler(MyRestCallHandler.class) .build();

      Notes:
      See Also:
      Returns:
      The creator for the rest call handler.

    • callHandler

      public RestClient.Builder callHandler(Class<? extends RestCallHandler> value)
      REST call handler class.

      Specifies a custom handler for making HTTP calls.

      This is a shortcut for callHandler().type(value).

      Parameters:
      value - The new value for this setting.
      Cannot be null.
      Returns:
      This object.
      See Also:

    • clientVersion

      public RestClient.Builder clientVersion(String value)
      Sets the client version by setting the value for the "Client-Version" header.

      This is a shortcut for calling headerData().append(ClientVersion.of(value)).

      Parameters:
      value - The version string (e.g. "1.2.3")
      Can be null (no Client-Version header will be added).
      Returns:
      This object.
      See Also:

    • connectionBackoffStrategy

      public RestClient.Builder connectionBackoffStrategy(ConnectionBackoffStrategy connectionBackoffStrategy)
      Assigns ConnectionBackoffStrategy instance.
      Parameters:
      connectionBackoffStrategy - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • connectionManager

      public RestClient.Builder connectionManager(HttpClientConnectionManager value)
      Assigns HttpClientConnectionManager instance.
      Parameters:
      value - New property value.
      Can be null (value will not be set, a default connection manager will be created).
      Returns:
      This object.
      See Also:

    • connectionManagerShared

      public RestClient.Builder connectionManagerShared(boolean shared)
      Defines the connection manager is to be shared by multiple client instances.
      Notes:
      • If the connection manager is shared its life-cycle is expected to be managed by the caller and it will not be shut down if the client is closed.
      Parameters:
      shared - New property value.
      Returns:
      This object.
      See Also:

    • connectionReuseStrategy

      public RestClient.Builder connectionReuseStrategy(ConnectionReuseStrategy reuseStrategy)
      Assigns ConnectionReuseStrategy instance.
      Parameters:
      reuseStrategy - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • connectionTimeToLive

      public RestClient.Builder connectionTimeToLive(long connTimeToLive, TimeUnit connTimeToLiveTimeUnit)
      Sets maximum time to live for persistent connections.
      Notes:
      Parameters:
      connTimeToLive - New property value.
      connTimeToLiveTimeUnit - New property value.
      Cannot be null.
      Returns:
      This object.
      See Also:

    • console

      public RestClient.Builder console(PrintStream value)
      Console print stream

      Allows you to redirect the console output to a different print stream.

      Parameters:
      value - The new value for this setting.
      Can be null (defaults to System.err).
      Returns:
      This object.

    • contentDecoderRegistry

      public RestClient.Builder contentDecoderRegistry(Map<String,InputStreamFactory> contentDecoderMap)
      Assigns a map of InputStreamFactories to be used for automatic content decompression.
      Parameters:
      contentDecoderMap - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • contentType

      public RestClient.Builder contentType(String value)
      Sets the value for the Content-Type request header on all requests.

      This is a shortcut for calling headerData().append(ContentType.of(value)).

      This overrides the media type specified on the serializer.

      Parameters:
      value - The new header value.
      Can be null (no Content-Type header will be added).
      Returns:
      This object.
      See Also:

    • copy

      public RestClient.Builder copy()
      Description copied from class: Context.Builder
      Copy creator.
      Specified by:
      copy in class BeanContextable.Builder
      Returns:
      A new mutable copy of this builder.

    • debug

      public RestClient.Builder debug()
      Sets the value for the Debug request header on all requests.

      This is a shortcut for calling headerData().append(Debug.of(value)).

      Overrides:
      debug in class BeanContextable.Builder
      Returns:
      This object.
      See Also:

    • debugOutputLines

      public RestClient.Builder debugOutputLines(int value)
      Parser configuration property:  Debug output lines.

      When parse errors occur, this specifies the number of lines of input before and after the error location to be printed as part of the exception message.

      Example:

      // Create a parser whose exceptions print out 100 lines before and after the parse error location. RestClient client = RestClient .create() .json() .debug() // Enable debug mode to capture Reader contents as strings. .debugOuputLines(100) .build(); // Try to parse some bad JSON. try { client .get("/pathToBadJson") .run() .getContent().as(Object.class); // Try to parse it. } catch (RestCallException e) { System.err.println(e.getMessage()); // Will display 200 lines of the output. }

      See Also:
      Parameters:
      value - The new value for this property.
      The default value is 5.
      Returns:
      This object.

    • defaultAuthSchemeRegistry

      public RestClient.Builder defaultAuthSchemeRegistry(Lookup<AuthSchemeProvider> authSchemeRegistry)
      Assigns default AuthScheme registry which will be used for request execution if not explicitly set in the client execution context.
      Parameters:
      authSchemeRegistry - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • defaultConnectionConfig

      public RestClient.Builder defaultConnectionConfig(ConnectionConfig config)
      Assigns default ConnectionConfig.
      Notes:
      Parameters:
      config - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • defaultCookieSpecRegistry

      public RestClient.Builder defaultCookieSpecRegistry(Lookup<CookieSpecProvider> cookieSpecRegistry)
      Assigns default CookieSpec registry which will be used for request execution if not explicitly set in the client execution context.
      Parameters:
      cookieSpecRegistry - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • defaultCookieStore

      public RestClient.Builder defaultCookieStore(CookieStore cookieStore)
      Assigns default CookieStore instance which will be used for request execution if not explicitly set in the client execution context.
      Parameters:
      cookieStore - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • defaultCredentialsProvider

      public RestClient.Builder defaultCredentialsProvider(CredentialsProvider credentialsProvider)
      Assigns default CredentialsProvider instance which will be used for request execution if not explicitly set in the client execution context.
      Parameters:
      credentialsProvider - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • defaultRequestConfig

      public RestClient.Builder defaultRequestConfig(RequestConfig config)
      Assigns default RequestConfig instance which will be used for request execution if not explicitly set in the client execution context.
      Parameters:
      config - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • defaultSocketConfig

      public RestClient.Builder defaultSocketConfig(SocketConfig config)
      Assigns default SocketConfig.
      Notes:
      Parameters:
      config - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • detectLeaks

      public RestClient.Builder detectLeaks()
      RestClient configuration property:  Enable leak detection.

      Enable client and request/response leak detection.

      Causes messages to be logged to the console if clients or request/response objects are not properly closed when the finalize methods are invoked.

      Automatically enabled with Context.Builder.debug().

      Example:

      // Create a client that logs a message if RestClient client = RestClient .create() .detectLeaks() .logToConsole() // Also log the error message to System.err .build(); client.closeQuietly(); // Customized HttpClient won't be closed.

      Returns:
      This object.

    • detectRecursions

      public RestClient.Builder detectRecursions()
      BeanTraverse configuration property:  Automatically detect POJO recursions.

      When enabled, specifies that recursions should be checked for during traversal.

      Recursions can occur when traversing models that aren't true trees but rather contain loops.
      In general, unchecked recursions cause stack-overflow-errors.
      These show up as BeanRecursionException with the message "Depth too deep. Stack overflow occurred.".

      Notes:
      • Checking for recursion can cause a small performance penalty.
      Example:

      // Create a JSON client that automatically checks for recursions. RestClient client = RestClient .create() .json() .detectRecursions() .build(); // Create a POJO model with a recursive loop. public class A { public Object f; } A a = new A(); a.f = a; try { // Throws a RestCallException with an inner SerializeException and not a StackOverflowError client .post("http://localhost:10000/foo", a) .run(); } catch (RestCallException e} { // Handle exception. }

      See Also:
      Returns:
      This object.

    • dictionaryOn

      public RestClient.Builder dictionaryOn(Class<?> on, Class<?>... values)
      Description copied from class: BeanContextable.Builder
      Bean dictionary.

      This is identical to BeanContextable.Builder.beanDictionary(Class...), but specifies a dictionary within the context of a single class as opposed to globally.

      Example:

      // POJOs with @Bean(name) annotations. @Bean(typeName="foo") public class Foo {...} @Bean(typeName="bar") public class Bar {...} // A bean with a field with an indeterminate type. public class MyBean { public Object mySimpleField; } // Create a parser and tell it which classes to try to resolve. ReaderParser parser = JsonParser .create() .dictionaryOn(MyBean.class, Foo.class, Bar.class) .build(); // Parse bean. MyBean bean = parser.parse("{mySimpleField:{_type:'foo',...}}", MyBean.class);

      This is functionally equivalent to the Bean.dictionary() annotation.

      See Also:
      Overrides:
      dictionaryOn in class BeanContextable.Builder
      Parameters:
      on - The class that the dictionary values apply to.
      Cannot be null.
      values - The new values for this setting.
      Cannot contain null values.
      Returns:
      This object.

    • disableAuthCaching

      public RestClient.Builder disableAuthCaching()
      Disables authentication scheme caching.
      Notes:
      Returns:
      This object.
      See Also:

    • disableAutomaticRetries

      public RestClient.Builder disableAutomaticRetries()
      Disables automatic request recovery and re-execution.
      Returns:
      This object.
      See Also:

    • disableBeansRequireSomeProperties

      public RestClient.Builder disableBeansRequireSomeProperties()
      Description copied from class: BeanContextable.Builder
      Beans don't require at least one property.

      When enabled, then a Java class doesn't need to contain at least 1 property to be considered a bean. Otherwise, the bean will be serialized as a string using the Object.toString() method.

      The @Bean annotation can be used on a class to override this setting when true.

      Example:

      // A bean with no properties. public class MyBean { } // Create a serializer that serializes beans even if they have zero properties. WriterSerializer serializer = JsonSerializer .create() .disableBeansRequireSomeProperties() .build(); // Produces: {} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Bean annotation can be used on the class to force it to be recognized as a bean class even if it has no properties.
      See Also:
      Overrides:
      disableBeansRequireSomeProperties in class BeanContextable.Builder
      Returns:
      This object.

    • disableConnectionState

      public RestClient.Builder disableConnectionState()
      Disables connection state tracking.
      Returns:
      This object.
      See Also:

    • disableContentCompression

      public RestClient.Builder disableContentCompression()
      Disables automatic content decompression.
      Notes:
      Returns:
      This object.
      See Also:

    • disableCookieManagement

      public RestClient.Builder disableCookieManagement()
      Disables state (cookie) management.
      Notes:
      Returns:
      This object.
      See Also:

    • disableIgnoreMissingSetters

      public RestClient.Builder disableIgnoreMissingSetters()
      Description copied from class: BeanContextable.Builder
      Don't silently ignore missing setters.

      When enabled, trying to set a value on a bean property without a setter will throw a BeanRuntimeException. Otherwise, it will be silently ignored.

      Example:

      // A bean with a property with a getter but not a setter. public class MyBean { public void getFoo() { return "foo"; } } // Create a parser that throws an exception if a setter is not found but a getter is. ReaderParser parser = JsonParser .create() .disableIgnoreMissingSetters() .build(); // Throws a ParseException. MyBean bean = parser.parse("{foo:'bar'}", MyBean.class);

      Notes:
      • The @BeanIgnore annotation can also be used on getters and fields to ignore them.
      See Also:
      Overrides:
      disableIgnoreMissingSetters in class BeanContextable.Builder
      Returns:
      This object.

    • disableIgnoreTransientFields

      public RestClient.Builder disableIgnoreTransientFields()
      Description copied from class: BeanContextable.Builder
      Don't ignore transient fields.

      When enabled, methods and fields marked as transient will not be ignored as bean properties.

      Example:

      // A bean with a transient field. public class MyBean { public transient String foo = "foo"; } // Create a serializer that doesn't ignore transient fields. WriterSerializer serializer = JsonSerializer .create() .disableIgnoreTransientFields() .build(); // Produces: {"foo":"foo"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Beanp annotation can also be used on transient fields to keep them from being ignored.
      See Also:
      Overrides:
      disableIgnoreTransientFields in class BeanContextable.Builder
      Returns:
      This object.

    • disableIgnoreUnknownNullBeanProperties

      public RestClient.Builder disableIgnoreUnknownNullBeanProperties()
      Description copied from class: BeanContextable.Builder
      Don't ignore unknown properties with null values.

      When enabled, trying to set a null value on a non-existent bean property will throw a BeanRuntimeException. Otherwise it will be silently ignored.

      Example:

      // A bean with a single property. public class MyBean { public String foo; } // Create a parser that throws an exception on an unknown property even if the value being set is null. ReaderParser parser = JsonParser .create() .disableIgnoreUnknownNullBeanProperties() .build(); // Throws a BeanRuntimeException wrapped in a ParseException on the unknown 'bar' property. MyBean bean = parser.parse("{foo:'foo',bar:null}", MyBean.class);

      See Also:
      Overrides:
      disableIgnoreUnknownNullBeanProperties in class BeanContextable.Builder
      Returns:
      This object.

    • disableInterfaceProxies

      public RestClient.Builder disableInterfaceProxies()
      Description copied from class: BeanContextable.Builder
      Don't use interface proxies.

      When enabled, interfaces will be instantiated as proxy classes through the use of an InvocationHandler if there is no other way of instantiating them. Otherwise, throws a BeanRuntimeException.

      See Also:
      Overrides:
      disableInterfaceProxies in class BeanContextable.Builder
      Returns:
      This object.

    • disableRedirectHandling

      public RestClient.Builder disableRedirectHandling()
      Disables automatic redirect handling.
      Returns:
      This object.
      See Also:

    • errorCodes

      public RestClient.Builder errorCodes(Predicate<Integer> value)
      Errors codes predicate.

      Defines a predicate to test for error codes.

      Example:

      // Create a client that considers any 300+ responses to be errors. RestClient client = RestClient .create() .errorCodes(x -> x>=300) .build();

      Parameters:
      value - The new value for this setting.
      The default value is x -> x >= 400.
      Cannot be null.
      Returns:
      This object.

    • evictExpiredConnections

      public RestClient.Builder evictExpiredConnections()
      Makes this instance of HttpClient proactively evict expired connections from the connection pool using a background thread.
      Notes:
      • One MUST explicitly close HttpClient with Closeable.close() in order to stop and release the background thread.
      • This method has no effect if the instance of HttpClient is configured to use a shared connection manager.
      • This method may not be used when the instance of HttpClient is created inside an EJB container.
      Returns:
      This object.
      See Also:

    • evictIdleConnections

      public RestClient.Builder evictIdleConnections(long maxIdleTime, TimeUnit maxIdleTimeUnit)
      Makes this instance of HttpClient proactively evict idle connections from the connection pool using a background thread.
      Notes:
      • One MUST explicitly close HttpClient with Closeable.close() in order to stop and release the background thread.
      • This method has no effect if the instance of HttpClient is configured to use a shared connection manager.
      • This method may not be used when the instance of HttpClient is created inside an EJB container.
      Parameters:
      maxIdleTime - New property value.
      maxIdleTimeUnit - New property value.
      Cannot be null.
      Returns:
      This object.
      See Also:

    • executorService

      public RestClient.Builder executorService(ExecutorService executorService, boolean shutdownOnClose)
      RestClient configuration property:  Executor service.

      Defines the executor service to use when calling future methods on the RestRequest class.

      This executor service is used to create Future objects on the following methods:

      The default executor service is a single-threaded ThreadPoolExecutor with a 30 second timeout and a queue size of 10.

      Example:

      // Create a client with a customized executor service. RestClient client = RestClient .create() .executorService(new ThreadPoolExecutor(1, 1, 30, TimeUnit.SECONDS, new ArrayBlockingQueue<Runnable>(10)), true) .build(); // Use it to asynchronously run a request. Future<RestResponse> responseFuture = client.get(URI).runFuture(); // Do some other stuff. // Now read the response. String body = responseFuture.get().getContent().asString(); // Use it to asynchronously retrieve a response. Future<MyBean> myBeanFuture = client .get(URI) .run() .getContent().asFuture(MyBean.class); // Do some other stuff. // Now read the response. MyBean bean = myBeanFuture.get();

      Parameters:
      executorService - The executor service.
      Can be null (a default executor service will be created if needed).
      shutdownOnClose - Call ExecutorService.shutdown() when RestClient.close() is called.
      Returns:
      This object.

    • findFluentSetters

      public RestClient.Builder findFluentSetters()
      Description copied from class: BeanContextable.Builder
      Find fluent setters.

      When enabled, fluent setters are detected on beans during parsing.

      Fluent setters must have the following attributes:

      • Public.
      • Not static.
      • Take in one parameter.
      • Return the bean itself.
      Example:

      // A bean with a fluent setter. public class MyBean { public MyBean foo(String value) {...} } // Create a parser that finds fluent setters. ReaderParser parser = JsonParser .create() .findFluentSetters() .build(); // Parse into bean using fluent setter. MyBean bean = parser.parse("{foo:'bar'}", MyBean.class);

      Notes:
      • The @Beanp annotation can also be used on methods to individually identify them as fluent setters.
      • The @Bean.fluentSetters() annotation can also be used on classes to specify to look for fluent setters.
      See Also:
      Overrides:
      findFluentSetters in class BeanContextable.Builder
      Returns:
      This object.

    • findFluentSetters

      public RestClient.Builder findFluentSetters(Class<?> on)
      Description copied from class: BeanContextable.Builder
      Find fluent setters.

      Identical to BeanContextable.Builder.findFluentSetters() but enables it on a specific class only.

      Example:

      // A bean with a fluent setter. public class MyBean { public MyBean foo(String value) {...} } // Create a parser that finds fluent setters. ReaderParser parser = JsonParser .create() .findFluentSetters(MyBean.class) .build(); // Parse into bean using fluent setter. MyBean bean = parser.parse("{foo:'bar'}", MyBean.class);

      Notes:
      See Also:
      Overrides:
      findFluentSetters in class BeanContextable.Builder
      Parameters:
      on - The class that this applies to.
      Cannot be null.
      Returns:
      This object.

    • formData

      public final PartList formData()
      Returns the builder for the list of form data parameters that get applied to all requests created by this builder.

      This is the primary method for accessing the form data parameter list. On first call, the builder is created via the method createFormData().

      Example:

      // Create a client that adds a "foo=bar" form-data parameter on every request. RestClient.Builder builder = RestClient.create(); builder.formData().setDefault("foo", "bar")); RestClient client = builder.build();

      The following convenience methods are also provided for updating the parameters:

      Returns:
      The form data list builder.

    • formData

      public RestClient.Builder formData(NameValuePair... parts)
      Appends multiple form-data parameters to the request bodies of all URL-encoded form posts.
      Example:

      import static org.apache.juneau.http.HttpParts.*; RestClient client = RestClient .create() .formData( stringPart("foo", "bar"), booleanPart("baz", true) ) .build();

      This is a shortcut for calling formData().append(parts).

      Parameters:
      parts - The form-data parameters.
      Can contain null values (ignored).
      Returns:
      This object.
      See Also:

    • formData

      public RestClient.Builder formData(String name, String value)
      Appends a form-data parameter to all request bodies.
      Example:

      RestClient client = RestClient .create() .formData("foo", "bar") .build();

      This is a shortcut for calling formData().append(name,value).

      Parameters:
      name - The parameter name.
      Cannot be null.
      value - The parameter value.
      Can be null (null value will be serialized).
      Returns:
      This object.
      See Also:

    • formData

      public RestClient.Builder formData(String name, Supplier<String> value)
      Appends a form-data parameter with a dynamic value to all request bodies.
      Example:

      RestClient client = RestClient .create() .formData("foo", ()->"bar") .build();

      This is a shortcut for calling formData().append(name,value).

      Parameters:
      name - The parameter name.
      Cannot be null.
      value - The parameter value supplier.
      Can be null (null value will be serialized).
      Returns:
      This object.
      See Also:

    • formDataDefault

      public RestClient.Builder formDataDefault(NameValuePair... parts)
      Sets default form-data parameter values.

      Uses default values for specified parameters if not otherwise specified on the outgoing requests.

      Example:

      RestClient client = RestClient .create() .formDataDefault(stringPart("foo", ()->"bar")); .build();

      This is a shortcut for calling formData().setDefault(parts).

      Parameters:
      parts - The parts.
      Can contain null values (ignored).
      Returns:
      This object.
      See Also:

    • getRootUri

      public String getRootUri()
      Returns the root URI defined for this client.

      Returns null in leu of an empty string. Trailing slashes are trimmed.

      Returns:
      The root URI defined for this client.

    • header

      public RestClient.Builder header(String name, String value)
      Appends a header to all requests.
      Example:

      RestClient client = RestClient .create() .header("Foo", "bar"); .build();

      This is a shortcut for calling headerData().append(name,value).

      Parameters:
      name - The header name.
      Cannot be null.
      value - The header value.
      Can be null (null value will be serialized).
      Returns:
      This object.
      See Also:

    • header

      public RestClient.Builder header(String name, Supplier<String> value)
      Appends a header to all requests using a dynamic value.
      Example:

      RestClient client = RestClient .create() .header("Foo", ()->"bar"); .build();

      This is a shortcut for calling headerData().append(name,value).

      Parameters:
      name - The header name.
      Cannot be null.
      value - The header value supplier.
      Can be null (null value will be serialized).
      Returns:
      This object.
      See Also:

    • headers

      public final HeaderList headers()
      Returns the builder for the list of headers that get applied to all requests created by this builder.

      This is the primary method for accessing the request header list. On first call, the builder is created via the method createHeaderData().

      Example:

      // Create a client that adds a "Foo: bar" header on every request. RestClient.Builder builder = RestClient.create(); builder.headerData().setDefault("Foo", "bar")); RestClient client = builder.build();

      The following convenience methods are also provided for updating the headers:

      Returns:
      The header list builder.

    • headers

      public RestClient.Builder headers(Header... parts)
      Appends multiple headers to all requests.
      Example:

      import static org.apache.juneau.http.HttpHeaders.*; RestClient client = RestClient .create() .headers( ACCEPT_TEXT_XML, stringHeader("Foo", "bar") ) .build();

      This is a shortcut for calling headerData().append(parts).

      Parameters:
      parts - The header to set.
      Can contain null values (ignored).
      Returns:
      This object.
      See Also:

    • headersDefault

      public RestClient.Builder headersDefault(Header... parts)
      Sets default header values.

      Uses default values for specified headers if not otherwise specified on the outgoing requests.

      Example:

      RestClient client = RestClient .create() .headersDefault(stringHeader("Foo", ()->"bar")); .build();

      This is a shortcut for calling headerData().setDefault(parts).

      Parameters:
      parts - The header values.
      Can contain null values (ignored).
      Returns:
      This object.
      See Also:

    • html

      public RestClient.Builder html()
      Convenience method for specifying HTML as the marshalling transmission media type.

      POJOs are converted to HTML without any sort of doc wrappers.

      HtmlSerializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      • The serializer can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      HtmlParser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header will be set to "text/html" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Content-Type request header will be set to "text/html" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as json() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(HtmlSerializer.class).parser(HtmlParser.class).

      Example:

      // Construct a client that uses HTML marshalling. RestClient client = RestClient.create().html().build();

      Returns:
      This object.

    • htmlDoc

      public RestClient.Builder htmlDoc()
      Convenience method for specifying HTML DOC as the marshalling transmission media type.

      POJOs are converted to fully renderable HTML pages.

      HtmlDocSerializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      • The serializer can be configured using any of the serializer property setters (e.g. sortCollections() or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      HtmlParser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header will be set to "text/html" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Content-Type request header will be set to "text/html" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as json() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(HtmlDocSerializer.class).parser(HtmlParser.class).

      Example:

      // Construct a client that uses HTML Doc marshalling. RestClient client = RestClient.create().htmlDoc().build();

      Returns:
      This object.

    • htmlStrippedDoc

      public RestClient.Builder htmlStrippedDoc()
      Convenience method for specifying Stripped HTML DOC as the marshalling transmission media type.

      Same as htmlDoc() but without the header and body tags and page title and description.

      HtmlStrippedDocSerializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      • The serializer can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      HtmlParser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header will be set to "text/html+stripped" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Content-Type request header will be set to "text/html+stripped" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as json() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(HtmlStrippedDocSerializer.class).parser(HtmlParser.class).

      Example:

      // Construct a client that uses HTML Stripped Doc marshalling. RestClient client = RestClient.create().htmlStrippedDoc().build();

      Returns:
      This object.

    • httpClient

      public RestClient.Builder httpClient(CloseableHttpClient value)
      Sets the HttpClient to be used to handle all HTTP communications with the target server.

      This can be used to bypass the client created by createHttpClient() method.

      Example:

      // Construct a client that uses a customized HttpClient. RestClient client = RestClient .create() .httpClient(HttpClientBuilder.create().build()) .build();

      Parameters:
      value - The HttpClient to be used to handle all HTTP communications with the target server.
      Can be null (a default client will be created).
      Returns:
      This object.

    • httpClientBuilder

      public final HttpClientBuilder httpClientBuilder()
      Returns the HTTP client builder.
      Returns:
      The HTTP client builder.

    • httpClientBuilder

      public RestClient.Builder httpClientBuilder(HttpClientBuilder value)
      Sets the HttpClientBuilder that will be used to create the HttpClient used by RestClient.

      This can be used to bypass the builder created by createHttpClientBuilder() method.

      Example:

      // Construct a client that uses a customized HttpClientBuilder. RestClient client = RestClient .create() .httpClientBuilder(HttpClientBuilder.create()) .build();

      Parameters:
      value - The HttpClientBuilder that will be used to create the HttpClient used by RestClient.
      Can be null (a default builder will be created).
      Returns:
      This object.

    • httpProcessor

      public RestClient.Builder httpProcessor(HttpProcessor httpprocessor)
      Assigns HttpProcessor instance.
      Parameters:
      httpprocessor - New property value.
      Returns:
      This object.
      See Also:

    • ignoreErrors

      public RestClient.Builder ignoreErrors()
      Ignore errors.

      When enabled, HTTP error response codes (e.g. >=400) will not cause a RestCallException to be thrown.

      Note that this is equivalent to builder.errorCodes(x -> false);

      Example:

      // Create a client that doesn't throws a RestCallException when a 500 error occurs. RestClient .create() .ignoreErrors() .build() .get("/error") // Throws a 500 error .run() .assertStatus().is(500);

      Returns:
      This object.

    • ignoreInvocationExceptionsOnGetters

      public RestClient.Builder ignoreInvocationExceptionsOnGetters()
      Description copied from class: BeanContextable.Builder
      Ignore invocation errors on getters.

      When enabled, errors thrown when calling bean getter methods will silently be ignored. Otherwise, a BeanRuntimeException is thrown.

      Example:

      // A bean with a property that throws an exception. public class MyBean { public String getFoo() { throw new RuntimeException("foo"); } } // Create a serializer that ignores bean getter exceptions. WriterSerializer serializer = JsonSerializer .create() .ingoreInvocationExceptionsOnGetters() .build(); // Exception is ignored. String json = serializer.serialize(new MyBean());

      See Also:
      Overrides:
      ignoreInvocationExceptionsOnGetters in class BeanContextable.Builder
      Returns:
      This object.

    • ignoreInvocationExceptionsOnSetters

      public RestClient.Builder ignoreInvocationExceptionsOnSetters()
      Description copied from class: BeanContextable.Builder
      Ignore invocation errors on setters.

      When enabled, errors thrown when calling bean setter methods will silently be ignored. Otherwise, a BeanRuntimeException is thrown.

      Example:

      // A bean with a property that throws an exception. public class MyBean { public void setFoo(String foo) { throw new RuntimeException("foo"); } } // Create a parser that ignores bean setter exceptions. ReaderParser parser = JsonParser .create() .ignoreInvocationExceptionsOnSetters() .build(); // Exception is ignored. MyBean bean = parser.parse("{foo:'bar'}", MyBean.class);

      See Also:
      Overrides:
      ignoreInvocationExceptionsOnSetters in class BeanContextable.Builder
      Returns:
      This object.

    • ignoreRecursions

      public RestClient.Builder ignoreRecursions()
      BeanTraverse configuration property:  Ignore recursion errors.

      When enabled, when we encounter the same object when traversing a tree, we set the value to null.

      For example, if a model contains the links A->B->C->A, then the JSON generated will look like the following when BEANTRAVERSE_ignoreRecursions is true...

      {A:{B:{C:null}}}

      Notes:
      • Checking for recursion can cause a small performance penalty.
      Example:

      // Create a JSON client that ignores recursions. RestClient client = RestClient .create() .json() .ignoreRecursions() .build(); // Create a POJO model with a recursive loop. public class A { public Object f; } A a = new A(); a.f = a; // Produces request body "{f:null}" client .post("http://localhost:10000/foo", a) .run();

      See Also:
      Returns:
      This object.

    • ignoreUnknownBeanProperties

      public RestClient.Builder ignoreUnknownBeanProperties()
      Description copied from class: BeanContextable.Builder
      Ignore unknown properties.

      When enabled, trying to set a value on a non-existent bean property will silently be ignored. Otherwise, a BeanRuntimeException is thrown.

      Example:

      // A bean with a single property. public class MyBean { public String foo; } // Create a parser that ignores missing bean properties. ReaderParser parser = JsonParser .create() .ignoreUnknownBeanProperties() .build(); // Doesn't throw an exception on unknown 'bar' property. MyBean bean = parser.parse("{foo:'foo',bar:'bar'}", MyBean.class);

      See Also:
      Overrides:
      ignoreUnknownBeanProperties in class BeanContextable.Builder
      Returns:
      This object.

    • ignoreUnknownEnumValues

      public RestClient.Builder ignoreUnknownEnumValues()
      Description copied from class: BeanContextable.Builder
      Ignore unknown enum values.

      When enabled, unknown enum values are set to null instead of throwing a parse exception.

      See Also:
      Overrides:
      ignoreUnknownEnumValues in class BeanContextable.Builder
      Returns:
      This object.

    • impl

      public RestClient.Builder impl(Context value)
      Description copied from class: Context.Builder
      Specifies a pre-instantiated bean for the Context.Builder.build() method to return.

      If a non-null value is provided and it's an instance of the context type, Context.Builder.build() will return that instance instead of creating a new one. If null, the normal build process continues.

      Overrides:
      impl in class BeanContextable.Builder
      Parameters:
      value - The value for this setting.
      Can be null (normal build process will continue).
      Returns:
      This object.

    • implClass

      public RestClient.Builder implClass(Class<?> interfaceClass, Class<?> implClass)
      Description copied from class: BeanContextable.Builder
      Implementation classes.

      For interfaces and abstract classes this method can be used to specify an implementation class for the interface/abstract class so that instances of the implementation class are used when instantiated (e.g. during a parse).

      Example:

      // A bean interface. public interface MyBean { ... } // A bean implementation. public class MyBeanImpl implements MyBean { ... } // Create a parser that instantiates MyBeanImpls when parsing MyBeans. ReaderParser parser = JsonParser .create() .implClass(MyBean.class, MyBeanImpl.class) .build(); // Instantiates a MyBeanImpl, MyBean bean = parser.parse("...", MyBean.class);

      Overrides:
      implClass in class BeanContextable.Builder
      Parameters:
      interfaceClass - The interface class.
      Cannot be null.
      implClass - The implementation class.
      Cannot be null.
      Returns:
      This object.

    • implClasses

      public RestClient.Builder implClasses(Map<Class<?>,Class<?>> values)
      Description copied from class: BeanContextable.Builder
      Implementation classes.

      For interfaces and abstract classes this method can be used to specify an implementation class for the interface/abstract class so that instances of the implementation class are used when instantiated (e.g. during a parse).

      Example:

      // A bean with a single property. public interface MyBean { ... } // A bean with a single property. public class MyBeanImpl implements MyBean { ... } // Create a parser that instantiates MyBeanImpls when parsing MyBeans. ReaderParser parser = JsonParser .create() .implClasses(AMap.of(MyBean.class, MyBeanImpl.class)) .build(); // Instantiates a MyBeanImpl, MyBean bean = parser.parse("...", MyBean.class);

      Overrides:
      implClasses in class BeanContextable.Builder
      Parameters:
      values - The new value for this setting.
      Cannot be null.
      Returns:
      This object.

    • initialDepth

      public RestClient.Builder initialDepth(int value)
      BeanTraverse configuration property:  Initial depth.

      The initial indentation level at the root.

      Useful when constructing document fragments that need to be indented at a certain level when whitespace is enabled.

      Example:

      // Create a REST client with JSON serializer with whitespace enabled and an initial depth of 2. RestClient client = RestClient .create() .json() .ws() .initialDepth(2) .build(); // Our bean to serialize. public class MyBean { public String foo = null; } // Produces request body "\t\t{\n\t\t\t'foo':'bar'\n\t\t}\n" client .post("http://localhost:10000/foo", new MyBean()) .run();

      See Also:
      Parameters:
      value - The new value for this property.
      The default is 0.
      Returns:
      This object.

    • interceptors

      public RestClient.Builder interceptors(Class<?>... values) throws Exception
      RestClient configuration property:  Call interceptors.

      Adds an interceptor that can be called to hook into specified events in the lifecycle of a single request.

      Example:

      // Customized interceptor (note you can also extend from BasicRestCallInterceptor as well. public class MyRestCallInterceptor implements RestCallInterceptor { @Override public void onInit(RestRequest req) throws Exception { // Intercept immediately after RestRequest object is created and all headers/query/form-data has been // set on the request from the client. } @Override public void onConnect(RestRequest req, RestResponse res) throws Exception { // Intercept immediately after an HTTP response has been received. } @Override public void onClose(RestRequest req, RestResponse res) throws Exception { // Intercept when the response body is consumed. } } // Create a client with a customized interceptor. RestClient client = RestClient .create() .interceptors(MyRestCallInterceptor.class) .build();

      Notes:
      Parameters:
      values - The values to add to this setting.
      Can be implementations of any of the following:
      Can contain null values (ignored).
      Returns:
      This object.
      Throws:
      Exception - If one or more interceptors could not be created.

    • interceptors

      public RestClient.Builder interceptors(Object... value)
      Call interceptors.

      Adds an interceptor that gets called immediately after a connection is made.

      Example:

      // Create a client with a customized interceptor. RestClient client = RestClient .create() .interceptors( new RestCallInterceptor() { @Override public void onInit(RestRequest req) throws Exception { // Intercept immediately after RestRequest object is created and all headers/query/form-data has been // set on the request from the client. } @Override public void onConnect(RestRequest req, RestResponse res) throws Exception { // Intercept immediately after an HTTP response has been received. } @Override public void onClose(RestRequest req, RestResponse res) throws Exception { // Intercept when the response body is consumed. } } ) .build();

      Notes:
      Parameters:
      value - The values to add to this setting.
      Can be implementations of any of the following:
      Can contain null values (ignored).
      Returns:
      This object.

    • interfaceClass

      public RestClient.Builder interfaceClass(Class<?> on, Class<?> value)
      Description copied from class: BeanContextable.Builder
      Identifies a class to be used as the interface class for the specified class and all subclasses.

      When specified, only the list of properties defined on the interface class will be used during serialization. Additional properties on subclasses will be ignored.

      // Parent class or interface public abstract class A { public String foo = "foo"; } // Sub class public class A1 extends A { public String bar = "bar"; } // Create a serializer and define our interface class mapping. WriterSerializer serializer = JsonSerializer .create() .interfaceClass(A1.class, A.class) .build(); // Produces "{"foo":"foo"}" String json = serializer.serialize(new A1());

      This annotation can be used on the parent class so that it filters to all child classes, or can be set individually on the child classes.

      Notes:
      Overrides:
      interfaceClass in class BeanContextable.Builder
      Parameters:
      on - The class that the interface class applies to.
      Cannot be null.
      value - The new value for this setting.
      Cannot be null.
      Returns:
      This object.

    • interfaces

      public RestClient.Builder interfaces(Class<?>... value)
      Description copied from class: BeanContextable.Builder
      Identifies a set of interfaces.

      When specified, only the list of properties defined on the interface class will be used during serialization of implementation classes. Additional properties on subclasses will be ignored.

      // Parent class or interface public abstract class A { public String foo = "foo"; } // Sub class public class A1 extends A { public String bar = "bar"; } // Create a serializer and define our interface class mapping. WriterSerializer serializer = JsonSerializer .create() .interfaces(A.class) .build(); // Produces "{"foo":"foo"}" String json = serializer.serialize(new A1());

      This annotation can be used on the parent class so that it filters to all child classes, or can be set individually on the child classes.

      Notes:
      Overrides:
      interfaces in class BeanContextable.Builder
      Parameters:
      value - The new value for this setting.
      Cannot contain null values.
      Returns:
      This object.

    • json

      public RestClient.Builder json()
      Convenience method for specifying JSON as the marshalling transmission media type.

      JsonSerializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      • The serializer can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      JsonParser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header will be set to "application/json" unless overridden via headers(), or per-request via RestRequest.header(Header)}.

      Content-Type request header will be set to "application/json" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as xml() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(JsonSerializer.class).parser(JsonParser.class).

      Example:

      // Construct a client that uses JSON marshalling. RestClient client = RestClient.create().json().build();

      Returns:
      This object.

    • json5

      public RestClient.Builder json5()
      Convenience method for specifying Simplified JSON as the marshalling transmission media type.

      Simplified JSON is typically useful for automated tests because you can do simple string comparison of results without having to escape lots of quotes.

      Json5Serializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      • The serializer can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Json5Parser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header will be set to "application/json" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Content-Type request header will be set to "application/json5" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as xml() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(Json5Serializer.class).parser(Json5Parser.class).

      Example:

      // Construct a client that uses Simplified JSON marshalling. RestClient client = RestClient.create().json5().build();

      Returns:
      This object.

    • keepAliveStrategy

      public RestClient.Builder keepAliveStrategy(ConnectionKeepAliveStrategy keepAliveStrategy)
      Assigns ConnectionKeepAliveStrategy instance.
      Parameters:
      keepAliveStrategy - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • keepHttpClientOpen

      public RestClient.Builder keepHttpClientOpen()
      RestClient configuration property:  Keep HttpClient open.

      Don't close this client when the RestClient.close() method is called.

      Example:

      // Create a client with a customized client and don't close the client service. RestClient client = RestClient .create() .httpClient(myHttpClient) .keepHttpClientOpen() .build(); client.closeQuietly(); // Customized HttpClient won't be closed.

      Returns:
      This object.

    • keepNullProperties

      public RestClient.Builder keepNullProperties()
      Serializer configuration property:  Don't trim null bean property values.

      When enabled, null bean values will be serialized to the output.

      Notes:
      • Not enabling this setting will cause Maps with null values to be lost during parsing.
      Example:

      // Create a REST client with JSON serializer that serializes null properties. RestClient client = RestClient .create() .json() .keepNullProperties() .build(); // Our bean to serialize. public class MyBean { public String foo = null; } // Request body will contain: {foo:null} client .post("http://localhost:10000/foo", new MyBean()) .run();

      See Also:
      Returns:
      This object.

    • locale

      public RestClient.Builder locale(Locale value)
      Description copied from class: BeanContextable.Builder
      Context configuration property:  Locale.

      Specifies the default locale for serializer and parser sessions when not specified via BeanSession.Builder.locale(Locale). Typically used for POJO swaps that need to deal with locales such as swaps that convert Date and Calendar objects to strings by accessing it via the session passed into the ObjectSwap.swap(BeanSession, Object) and ObjectSwap.unswap(BeanSession, Object, ClassMeta, String) methods.

      Example:

      // Define a POJO swap that skips serializing beans if we're in the UK. public class MyBeanSwap extends StringSwap<MyBean> { @Override public String swap(BeanSession session, MyBean bean) throws Exception { if (session.getLocale().equals(Locale.UK)) return null; return bean.toString(); } } // Create a serializer that uses the specified locale if it's not passed in through session args. WriterSerializer serializer = JsonSerializer .create() .locale(Locale.UK) .swaps(MyBeanSwap.class) .build();

      See Also:
      Overrides:
      locale in class BeanContextable.Builder
      Parameters:
      value - The new value for this property.
      Cannot be null.
      Returns:
      This object.

    • logger

      public RestClient.Builder logger(Logger value)
      Logger.

      Specifies the logger to use for logging.

      If not specified, uses the following logger:

      Logger.getLogger(RestClient.class.getName());

      Example:

      // Construct a client that logs messages to a special logger. RestClient client = RestClient .create() .logger(Logger.getLogger("MyLogger")) // Log to MyLogger logger. .logToConsole() // Also log to console. .logRequests(FULL, WARNING) // Log requests with full detail at WARNING level. .build();

      Parameters:
      value - The logger to use for logging.
      Can be null (defaults to Logger.getLogger(RestClient.class.getName())).
      Returns:
      This object.

    • logRequests

      public RestClient.Builder logRequests(DetailLevel detail, Level level, BiPredicate<RestRequest,RestResponse> test)
      Log requests.

      Causes requests/responses to be logged at the specified log level at the end of the request.

      SIMPLE detail produces a log message like the following:

      POST http://localhost:10000/testUrl, HTTP/1.1 200 OK

      FULL detail produces a log message like the following:

      === HTTP Call (outgoing) ======================================================= === REQUEST === POST http://localhost:10000/testUrl ---request headers--- Debug: true No-Trace: true Accept: application/json ---request entity--- Content-Type: application/json ---request content--- {"foo":"bar","baz":123} === RESPONSE === HTTP/1.1 200 OK ---response headers--- Content-Type: application/json;charset=utf-8 Content-Length: 21 Server: Jetty(8.1.0.v20120127) ---response content--- {"message":"OK then"} === END ========================================================================

      By default, the message is logged to the default logger. It can be logged to a different logger via the logger(Logger) method or logged to the console using the logToConsole() method.

      Parameters:
      detail - The detail level of logging.
      level - The log level.
      test - A predicate to use per-request to see if the request should be logged. If null, always logs.
      Returns:
      This object.

    • logToConsole

      public RestClient.Builder logToConsole()
      Log to console.

      Specifies to log messages to the console.

      Example:

      // Construct a client that logs messages to a special logger. RestClient client = RestClient .create() .logToConsole() .logRequests(FULL, INFO) // Level is ignored when logging to console. .build();

      Returns:
      This object.

    • marshaller

      public RestClient.Builder marshaller(Marshaller value)
      RestClient configuration property:  Marshaller

      Shortcut for specifying the serializers and parsers using the serializer and parser defined in a marshaller.

      Notes:
      • When using this method that takes in a pre-instantiated serializers and parsers, the serializer property setters (e.g. sortCollections()), parser property setters (e.g. strict()), or bean context property setters (e.g. swaps(Class...)) defined on this builder class have no effect.
      Example:

      // Create a client that uses Simplified-JSON transport using an existing marshaller. RestClient client = RestClient .create() .marshaller(Json5.DEFAULT_READABLE) .build();

      Parameters:
      value - The values to add to this setting.
      Can be null (value will not be set, existing serializers and parsers will be kept).
      Returns:
      This object.

    • marshallers

      public RestClient.Builder marshallers(Marshaller... value)
      RestClient configuration property:  Marshalls

      Shortcut for specifying the serializers and parsers using the serializer and parser defined in a marshaller.

      Notes:
      • When using this method that takes in a pre-instantiated serializers and parsers, the serializer property setters (e.g. sortCollections()), parser property setters (e.g. strict()), or bean context property setters (e.g. swaps(Class...)) defined on this builder class have no effect.
      Example:

      // Create a client that uses JSON and XML transport using existing marshalls. RestClient client = RestClient .create() .marshaller(Json.DEFAULT_READABLE, Xml.DEFAULT_READABLE) .build();

      Parameters:
      value - The values to add to this setting.
      Can contain null values (ignored).
      Returns:
      This object.

    • maxConnPerRoute

      public RestClient.Builder maxConnPerRoute(int maxConnPerRoute)
      Assigns maximum connection per route value.
      Notes:
      Parameters:
      maxConnPerRoute - New property value.
      Returns:
      This object.
      See Also:

    • maxConnTotal

      public RestClient.Builder maxConnTotal(int maxConnTotal)
      Assigns maximum total connection value.
      Notes:
      Parameters:
      maxConnTotal - New property value.
      Returns:
      This object.
      See Also:

    • maxDepth

      public RestClient.Builder maxDepth(int value)
      BeanTraverse configuration property:  Max serialization depth.

      When enabled, abort traversal if specified depth is reached in the POJO tree.

      If this depth is exceeded, an exception is thrown.

      This prevents stack overflows from occurring when trying to traverse models with recursive references.

      Example:

      // Create a REST client with JSON serializer that throws an exception if the depth reaches greater than 20. RestClient client = RestClient .create() .json() .maxDepth(20) .build();

      See Also:
      Parameters:
      value - The new value for this property.
      The default is 100.
      Returns:
      This object.

    • maxIndent

      public RestClient.Builder maxIndent(int value)
      WriterSerializer configuration property:  Maximum indentation.

      Specifies the maximum indentation level in the serialized document.

      Notes:
      • This setting does not apply to the RDF serializers.
      Example:

      // Create a REST client with JSON serializer that indents a maximum of 20 tabs. RestClient client = RestClient .create() .json() .ws() // Enable whitespace .maxIndent(20) .build();

      See Also:
      Parameters:
      value - The new value for this property.
      The default is 100.
      Returns:
      This object.

    • mediaType

      public RestClient.Builder mediaType(MediaType value)
      Appends the Accept and Content-Type headers on all requests made by this client.

      Headers are appended to the end of the current header list.

      This is a shortcut for calling headerData().append(Accept.of(value), ContentType.of(value)).

      Overrides:
      mediaType in class BeanContextable.Builder
      Parameters:
      value - The new header values.
      Can be null (no Accept or Content-Type headers will be added).
      Returns:
      This object.
      See Also:

    • mediaType

      public RestClient.Builder mediaType(String value)
      Appends the Accept and Content-Type headers on all requests made by this client.

      Headers are appended to the end of the current header list.

      This is a shortcut for calling headerData().append(Accept.of(value), ContentType.of(value)).

      Parameters:
      value - The new header values.
      Can be null (no Accept or Content-Type headers will be added).
      Returns:
      This object.
      See Also:

    • msgPack

      public RestClient.Builder msgPack()
      Convenience method for specifying MessagePack as the marshalling transmission media type.

      MessagePack is a binary equivalent to JSON that takes up considerably less space than JSON.

      MsgPackSerializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      • The serializer can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      MsgPackParser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header will be set to "octal/msgpack" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Content-Type request header will be set to "octal/msgpack" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as json() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(MsgPackSerializer.class).parser(MsgPackParser.class).

      Example:

      // Construct a client that uses MessagePack marshalling. RestClient client = RestClient.create().msgPack().build();

      Returns:
      This object.

    • notBeanClasses

      public RestClient.Builder notBeanClasses(Class<?>... values)
      Description copied from class: BeanContextable.Builder
      Bean class exclusions.

      List of classes that should not be treated as beans even if they appear to be bean-like. Not-bean classes are converted to Strings during serialization.

      Values can consist of any of the following types:

      • Classes.
      • Arrays and collections of classes.
      Example:

      // A bean with a single property. public class MyBean { public String foo = "bar"; public String toString() { return "baz"; } } // Create a serializer that doesn't treat MyBean as a bean class. WriterSerializer serializer = JsonSerializer .create() .notBeanClasses(MyBean.class) .build(); // Produces "baz" instead of {"foo":"bar"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @BeanIgnore annotation can also be used on classes to prevent them from being recognized as beans.
      See Also:
      Overrides:
      notBeanClasses in class BeanContextable.Builder
      Parameters:
      values - The values to add to this setting.
      Values can consist of any of the following types:
      • Classes.
      • Arrays and collections of classes.

      Cannot contain null values.
      Returns:
      This object.

    • notBeanPackages

      public RestClient.Builder notBeanPackages(String... values)
      Description copied from class: BeanContextable.Builder
      Bean package exclusions.

      Used as a convenient way of defining the BeanContext.Builder.notBeanClasses(Class...) property for entire packages. Any classes within these packages will be serialized to strings using Object.toString().

      Note that you can specify suffix patterns to include all subpackages.

      Values can consist of any of the following types:

      • Strings.
      • Arrays and collections of strings.
      Example:

      // Create a serializer that ignores beans in the specified packages. WriterSerializer serializer = JsonSerializer .create() .notBeanPackages("org.apache.foo", "org.apache.bar.*") .build();

      See Also:
      Overrides:
      notBeanPackages in class BeanContextable.Builder
      Parameters:
      values - The values to add to this setting.
      Values can consist of any of the following types:
      • Package objects.
      • Strings.
      • Arrays and collections of anything in this list.

      Cannot contain null values.
      Returns:
      This object.

    • noTrace

      public RestClient.Builder noTrace()
      When called, No-Trace: true is added to requests.

      This gives the opportunity for the servlet to not log errors on invalid requests. This is useful for testing purposes when you don't want your log file to show lots of errors that are simply the results of testing.

      It's up to the server to decide whether to allow for this. The BasicTestRestLogger class watches for this header and prevents logging of status 400+ responses to prevent needless logging of test scenarios.

      Returns:
      This object.
      See Also:

    • oapiCollectionFormat

      public RestClient.Builder oapiCollectionFormat(HttpPartCollectionFormat value)
      OpenApiCommon configuration property:  Default collection format for HTTP parts.

      Specifies the collection format to use for HTTP parts when not otherwise specified via Schema.collectionFormat() for the OpenAPI serializer and parser on this client.

      Example:

      // Create a REST client with CSV format for http parts. RestClient client = RestClient .create() .collectionFormat(CSV) .build(); // An arbitrary data structure. AList list = AList.of( "foo", "bar", AMap.of( "baz", AList.of("qux","true","123") ) ); // Set a header with a comma-separated list. client .get("/uri") .header("Foo", list) // Will be serialized as: foo=bar,baz=qux\,true\,123 .run();

      • HttpPartCollectionFormat
        • CSV - (default) Comma-separated values (e.g. "foo,bar").
        • SSV - Space-separated values (e.g. "foo bar").
        • TSV - Tab-separated values (e.g. "foo\tbar").
        • PIPES - Pipe-separated values (e.g. "foo|bar").
        • MULTI - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. "foo=bar&foo=baz").
        • UONC - UON collection notation (e.g. "@(foo,bar)").
      See Also:
      Parameters:
      value - The new value for this property.
      The default value is HttpPartCollectionFormat.NO_COLLECTION_FORMAT.
      Cannot be null.
      Returns:
      This object.

    • oapiFormat

      public RestClient.Builder oapiFormat(HttpPartFormat value)
      OpenApiCommon configuration property:  Default OpenAPI format for HTTP parts.

      Specifies the format to use for HTTP parts when not otherwise specified via Schema.format() for the OpenAPI serializer and parser on this client.

      Example:

      // Create a REST client with UON part serialization and parsing. RestClient client = RestClient .create() .oapiFormat(UON) .build(); // Set a header with a value in UON format. client .get("/uri") .header("Foo", "bar baz") // Will be serialized as: 'bar baz' .run();

      See Also:
      Parameters:
      value - The new value for this property.
      The default value is HttpPartFormat.NO_FORMAT.
      Cannot be null.
      Returns:
      This object.

    • openApi

      public RestClient.Builder openApi()
      Convenience method for specifying OpenAPI as the marshalling transmission media type.

      OpenAPI is a language that allows serialization to formats that use HttpPartSchema objects to describe their structure.

      OpenApiSerializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      OpenApiParser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      Accept request header will be set to "text/openapi" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Content-Type request header will be set to "text/openapi" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as json() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(OpenApiSerializer.class).parser(OpenApiParser.class).

      Example:

      // Construct a client that uses OpenAPI marshalling. RestClient client = RestClient.create().openApi().build();

      Returns:
      This object.

    • paramFormat

      public RestClient.Builder paramFormat(ParamFormat value)
      UonSerializer configuration property:  Parameter format.

      Specifies the format of parameters when using the UrlEncodingSerializer to serialize Form Posts.

      Specifies the format to use for GET parameter keys and values.

      Example:

      // Create a REST client with URL-Encoded serializer that serializes values in plain-text format. RestClient client = RestClient .create() .urlEnc() .paramFormat(PLAINTEXT) .build(); // An arbitrary data structure. AMap map = AMap.of( "foo", "bar", "baz", new String[]{"qux", "true", "123"} ); // Request body will be serialized as: foo=bar,baz=qux,true,123 client .post("/uri", map) .run();

      See Also:
      Parameters:
      value - The new value for this property.
      Cannot be null.
      Returns:
      This object.

    • paramFormatPlain

      public RestClient.Builder paramFormatPlain()
      UonSerializer configuration property:  Parameter format.

      Specifies the format of parameters when using the UrlEncodingSerializer to serialize Form Posts.

      Specifies plaintext as the format to use for GET parameter keys and values.

      Example:

      // Create a REST client with URL-Encoded serializer that serializes values in plain-text format. RestClient client = RestClient .create() .urlEnc() .build(); // An arbitrary data structure. AMap map = AMap.of( "foo", "bar", "baz", new String[]{"qux", "true", "123"} ); // Request body will be serialized as: foo=bar,baz=qux,true,123 client .post("/uri", map) .run();

      See Also:
      Returns:
      This object.

    • parser

      public RestClient.Builder parser(Class<? extends Parser> value)
      Parser.

      Associates the specified Parser with the HTTP client.

      The parser is used to parse the HTTP response body into a POJO.

      Notes:
      • When using this method that takes in a class, the parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.
      Example:

      // Create a client that uses JSON transport for response bodies. RestClient client = RestClient .create() .parser(JsonParser.class) .strict() // Enable strict mode on JsonParser. .build();

      Parameters:
      value - The new value for this setting.
      The default value is JsonParser.DEFAULT.
      Returns:
      This object.

    • parser

      public RestClient.Builder parser(Parser value)
      Parser.

      Associates the specified Parser with the HTTP client.

      The parser is used to parse the HTTP response body into a POJO.

      Notes:
      • When using this method that takes in a pre-instantiated parser, the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class have no effect.
      Example:

      // Create a client that uses a predefined JSON parser for response bodies. RestClient client = RestClient .create() .parser(JsonParser.DEFAULT_STRICT) .build();

      Parameters:
      value - The new value for this setting.
      The default value is JsonParser.DEFAULT.
      Cannot be null.
      Returns:
      This object.

    • parsers

      public final ParserSet.Builder parsers()
      Returns the parser group sub-builder.
      Returns:
      The parser group sub-builder.

    • parsers

      public RestClient.Builder parsers(Class<? extends Parser>... value)
      Parsers.

      Associates the specified Parsers with the HTTP client.

      The parsers are used to parse the HTTP response body into a POJO.

      The parser that best matches the Accept header will be used to parse the response body.
      If no Accept header is specified, the first parser in the list will be used.

      Notes:
      • When using this method that takes in classes, the parsers can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.
      Example:

      // Create a client that uses JSON and XML transport for response bodies. RestClient client = RestClient .create() .parser(JsonParser.class, XmlParser.class) .strict() // Enable strict mode on parsers. .build();

      Parameters:
      value - The new value for this setting.
      The default value is JsonParser.DEFAULT.
      Returns:
      This object.

    • parsers

      public RestClient.Builder parsers(Parser... value)
      Parsers.

      Associates the specified Parsers with the HTTP client.

      The parsers are used to parse the HTTP response body into a POJO.

      The parser that best matches the Accept header will be used to parse the response body.
      If no Accept header is specified, the first parser in the list will be used.

      Notes:
      • When using this method that takes in pre-instantiated parsers, the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class have no effect.
      Example:

      // Create a client that uses JSON and XML transport for response bodies. RestClient client = RestClient .create() .parser(JsonParser.DEFAULT_STRICT, XmlParser.DEFAULT) .build();

      Parameters:
      value - The new value for this setting.
      The default value is JsonParser.DEFAULT.
      Returns:
      This object.

    • partParser

      public final HttpPartParser.Creator partParser()
      Returns the part parser sub-builder.
      Returns:
      The part parser sub-builder.

    • partParser

      public RestClient.Builder partParser(Class<? extends HttpPartParser> value)
      Part parser.

      The parser to use for parsing POJOs from form data, query parameters, headers, and path variables.

      The default part parser is OpenApiParser which allows for schema-driven marshalling.

      Example:

      // Create a client that uses UON format by default for incoming HTTP parts. RestClient client = RestClient .create() .partParser(UonParser.class) .build();

      Parameters:
      value - The new value for this setting.
      The default value is OpenApiParser.
      Cannot be null.
      Returns:
      This object.

    • partParser

      public RestClient.Builder partParser(HttpPartParser value)
      Part parser.

      The parser to use for parsing POJOs from form data, query parameters, headers, and path variables.

      The default part parser is OpenApiParser which allows for schema-driven marshalling.

      Example:

      // Create a client that uses UON format by default for incoming HTTP parts. RestClient client = RestClient .create() .partParser(UonParser.DEFAULT) .build();

      Parameters:
      value - The new value for this setting.
      The default value is OpenApiParser.
      Cannot be null.
      Returns:
      This object.

    • partSerializer

      public final HttpPartSerializer.Creator partSerializer()
      Returns the part serializer sub-builder.
      Returns:
      The part serializer sub-builder.

    • partSerializer

      public RestClient.Builder partSerializer(Class<? extends HttpPartSerializer> value)
      Part serializer.

      The serializer to use for serializing POJOs in form data, query parameters, headers, and path variables.

      The default part serializer is OpenApiSerializer which allows for schema-driven marshalling.

      Example:

      // Create a client that uses UON format by default for outgoing HTTP parts. RestClient client = RestClient .create() .partSerializer(UonSerializer.class) .build();

      Parameters:
      value - The new value for this setting.
      The default value is OpenApiSerializer.
      Cannot be null.
      Returns:
      This object.

    • partSerializer

      public RestClient.Builder partSerializer(HttpPartSerializer value)
      Part serializer.

      The serializer to use for serializing POJOs in form data, query parameters, headers, and path variables.

      The default part serializer is OpenApiSerializer which allows for schema-driven marshalling.

      Example:

      // Create a client that uses UON format by default for outgoing HTTP parts. RestClient client = RestClient .create() .partSerializer(UonSerializer.DEFAULT) .build();

      Parameters:
      value - The new value for this setting.
      The default value is OpenApiSerializer.
      Cannot be null.
      Returns:
      This object.

    • pathData

      public final PartList pathData()
      Returns the builder for the list of path data parameters that get applied to all requests created by this builder.

      This is the primary method for accessing the path data parameter list. On first call, the builder is created via the method createFormData().

      Example:

      // Create a client that uses "bar" for the "{foo}" path variable on every request. RestClient.Builder builder = RestClient.create(); builder.pathData().setDefault("foo", "bar")); RestClient client = builder.build();

      The following convenience methods are also provided for updating the parameters:

      Returns:
      The form data list builder.

    • pathData

      public RestClient.Builder pathData(NameValuePair... parts)
      Sets multiple path parameters on all requests.
      Example:

      import static org.apache.juneau.http.HttpParts.*; RestClient client = RestClient .create() .pathData( stringPart("foo", "bar"), booleanPart("baz", true) ) .build();

      This is a shortcut for calling pathData().append(parts).

      Parameters:
      parts - The path parameters.
      Can contain null values (ignored).
      Returns:
      This object.
      See Also:

    • pathData

      public RestClient.Builder pathData(String name, String value)
      Appends a path parameter to all request bodies.
      Example:

      RestClient client = RestClient .create() .pathData("foo", "bar") .build();

      This is a shortcut for calling pathData().append(name,value).

      Parameters:
      name - The parameter name.
      Cannot be null.
      value - The parameter value.
      Can be null (null value will be serialized).
      Returns:
      This object.
      See Also:

    • pathData

      public RestClient.Builder pathData(String name, Supplier<String> value)
      Sets a path parameter with a dynamic value to all request bodies.
      Example:

      RestClient client = RestClient .create() .pathData("foo", ()->"bar") .build();

      This is a shortcut for calling pathData().append(name,value).

      Parameters:
      name - The parameter name.
      Cannot be null.
      value - The parameter value supplier.
      Can be null (null value will be serialized).
      Returns:
      This object.
      See Also:

    • pathDataDefault

      public RestClient.Builder pathDataDefault(NameValuePair... parts)
      Sets default path parameter values.

      Uses default values for specified parameters if not otherwise specified on the outgoing requests.

      Example:

      RestClient client = RestClient .create() .pathDataDefault(stringPart("foo", ()->"bar")); .build();

      This is a shortcut for calling pathData().setDefault(parts).

      Parameters:
      parts - The parts.
      Can contain null values (ignored).
      Returns:
      This object.
      See Also:

    • plainText

      public RestClient.Builder plainText()
      Convenience method for specifying Plain Text as the marshalling transmission media type.

      Plain text marshalling typically only works on simple POJOs that can be converted to and from strings using swaps, swap methods, etc...

      PlainTextSerializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      • The serializer can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      PlainTextParser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header will be set to "text/plain" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Content-Type request header will be set to "text/plain" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as json() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(PlainTextSerializer.class).parser(PlainTextParser.class).

      Example:

      // Construct a client that uses Plain Text marshalling. RestClient client = RestClient.create().plainText().build();

      Returns:
      This object.

    • pooled

      public RestClient.Builder pooled()
      When called, the createConnectionManager() method will return a PoolingHttpClientConnectionManager instead of a BasicHttpClientConnectionManager.
      Example:

      // Construct a client that uses pooled connections. RestClient client = RestClient .create() .pooled() .build();

      Returns:
      This object.

    • propertyNamer

      public RestClient.Builder propertyNamer(Class<?> on, Class<? extends PropertyNamer> value)
      Description copied from class: BeanContextable.Builder
      Bean property namer

      Same as BeanContextable.Builder.propertyNamer(Class) but allows you to specify a namer for a specific class.

      Example:

      // A bean with a single property. public class MyBean { public String fooBarBaz = "fooBarBaz"; } // Create a serializer that uses Dashed-Lower-Case property names for the MyBean class only. // (e.g. "foo-bar-baz" instead of "fooBarBaz") WriterSerializer serializer = JsonSerializer .create() .propertyNamer(MyBean.class, PropertyNamerDLC.class) .build(); // Produces: {"foo-bar-baz":"fooBarBaz"} String json = serializer.serialize(new MyBean());

      See Also:
      Overrides:
      propertyNamer in class BeanContextable.Builder
      Parameters:
      on - The class that the namer applies to.
      Cannot be null.
      value - The new value for this setting.
      The default is BasicPropertyNamer.
      Cannot be null.
      Returns:
      This object.

    • propertyNamer

      public RestClient.Builder propertyNamer(Class<? extends PropertyNamer> value)
      Description copied from class: BeanContextable.Builder
      Bean property namer

      The class to use for calculating bean property names.

      Predefined classes:

      Example:

      // A bean with a single property. public class MyBean { public String fooBarBaz = "fooBarBaz"; } // Create a serializer that uses Dashed-Lower-Case property names. // (e.g. "foo-bar-baz" instead of "fooBarBaz") WriterSerializer serializer = JsonSerializer .create() .propertyNamer(PropertyNamerDLC.class) .build(); // Produces: {"foo-bar-baz":"fooBarBaz"} String json = serializer.serialize(new MyBean());

      See Also:
      Overrides:
      propertyNamer in class BeanContextable.Builder
      Parameters:
      value - The new value for this setting.
      The default is BasicPropertyNamer.
      Cannot be null.
      Returns:
      This object.

    • proxy

      public RestClient.Builder proxy(HttpHost proxy)
      Assigns default proxy value.
      Notes:
      Parameters:
      proxy - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • proxyAuthenticationStrategy

      public RestClient.Builder proxyAuthenticationStrategy(AuthenticationStrategy proxyAuthStrategy)
      Assigns AuthenticationStrategy instance for proxy authentication.
      Parameters:
      proxyAuthStrategy - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • publicSuffixMatcher

      public RestClient.Builder publicSuffixMatcher(PublicSuffixMatcher publicSuffixMatcher)
      Assigns file containing public suffix matcher.
      Notes:
      Parameters:
      publicSuffixMatcher - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • queryData

      public final PartList queryData()
      Returns the builder for the list of query parameters that get applied to all requests created by this builder.

      This is the primary method for accessing the query parameter list. On first call, the builder is created via the method createQueryData().

      Example:

      // Create a client that adds a "foo=bar" query parameter on every request. RestClient.Builder builder = RestClient.create(); builder.queryData().setDefault("foo", "bar")); RestClient client = builder.build();

      The following convenience methods are also provided for updating the parameters:

      Returns:
      The query data list builder.

    • queryData

      public RestClient.Builder queryData(NameValuePair... parts)
      Appends multiple query parameters to the URI of all requests.
      Example:

      import static org.apache.juneau.http.HttpParts.*; RestClient client = RestClient .create() .queryData( stringPart("foo", "bar"), booleanPart("baz", true) ) .build();

      This is a shortcut for calling queryData().append(parts).

      Parameters:
      parts - The query parameters.
      Can contain null values (ignored).
      Returns:
      This object.
      See Also:

    • queryData

      public RestClient.Builder queryData(String name, String value)
      Appends a query parameter to the URI.
      Example:

      RestClient client = RestClient .create() .queryData("foo", "bar") .build();

      This is a shortcut for calling queryData().append(name,value).

      Parameters:
      name - The parameter name.
      Cannot be null.
      value - The parameter value.
      Can be null (null value will be serialized).
      Returns:
      This object.
      See Also:

    • queryData

      public RestClient.Builder queryData(String name, Supplier<String> value)
      Appends a query parameter with a dynamic value to the URI.
      Example:

      RestClient client = RestClient .create() .queryData("foo", ()->"bar") .build();

      This is a shortcut for calling queryData().append(name,value).

      Parameters:
      name - The parameter name.
      Cannot be null.
      value - The parameter value supplier.
      Can be null (null value will be serialized).
      Returns:
      This object.
      See Also:

    • queryDataDefault

      public RestClient.Builder queryDataDefault(NameValuePair... parts)
      Sets default query parameter values.

      Uses default values for specified parameters if not otherwise specified on the outgoing requests.

      Example:

      RestClient client = RestClient .create() .queryDataDefault(stringPart("foo", ()->"bar")); .build();

      This is a shortcut for calling queryData().setDefault(parts).

      Parameters:
      parts - The parts.
      Can contain null values (ignored).
      Returns:
      This object.
      See Also:

    • quoteChar

      public RestClient.Builder quoteChar(char value)
      WriterSerializer configuration property:  Quote character.

      Specifies the character to use for quoting attributes and values.

      Notes:
      • This setting does not apply to the RDF serializers.
      Example:

      // Create a REST client with JSON serializer that uses single quotes. RestClient client = RestClient .create() .json() .quoteChar('\'') .build(); // A bean with a single property public class MyBean { public String foo = "bar"; } // Request body will contain: {'foo':'bar'} client .post("http://localhost:10000/foo", new MyBean()) .run();

      See Also:
      Parameters:
      value - The new value for this property.
      The default is '"'.
      Returns:
      This object.

    • redirectStrategy

      public RestClient.Builder redirectStrategy(RedirectStrategy redirectStrategy)
      Assigns RedirectStrategy instance.
      Notes:
      Parameters:
      redirectStrategy - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • requestExecutor

      public RestClient.Builder requestExecutor(HttpRequestExecutor requestExec)
      Assigns HttpRequestExecutor instance.
      Parameters:
      requestExec - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • retryHandler

      public RestClient.Builder retryHandler(HttpRequestRetryHandler retryHandler)
      Assigns HttpRequestRetryHandler instance.
      Notes:
      Parameters:
      retryHandler - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • rootUrl

      public RestClient.Builder rootUrl(Object value)
      RestClient configuration property:  Root URI.

      When set, relative URI strings passed in through the various rest call methods (e.g. RestClient.get(Object) will be prefixed with the specified root.
      This root URI is ignored on those methods if you pass in a URL, URI, or an absolute URI string.

      Example:

      // Create a client that uses UON format by default for HTTP parts. RestClient client = RestClient .create() .rootUrl("http://localhost:10000/foo") .build(); Bar bar = client .get("/bar") // Relative to http://localhost:10000/foo .run() .getContent().as(Bar.class);

      Parameters:
      value - The root URI to prefix to relative URI strings.
      Trailing slashes are trimmed.
      Usually a String but you can also pass in URI and URL objects as well.
      Can be null (no root URL will be set).
      Returns:
      This object.

    • routePlanner

      public RestClient.Builder routePlanner(HttpRoutePlanner routePlanner)
      Assigns HttpRoutePlanner instance.
      Parameters:
      routePlanner - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • schemePortResolver

      public RestClient.Builder schemePortResolver(SchemePortResolver schemePortResolver)
      Assigns SchemePortResolver instance.
      Parameters:
      schemePortResolver - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • serializer

      public RestClient.Builder serializer(Class<? extends Serializer> value)
      Serializer.

      Associates the specified Serializer with the HTTP client.

      The serializer is used to serialize POJOs into the HTTP request body.

      Notes:
      • When using this method that takes in a class, the serializer can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.
      Example:

      // Create a client that uses JSON transport for request bodies. RestClient client = RestClient .create() .serializer(JsonSerializer.class) .sortCollections() // Sort any collections being serialized. .build();

      Parameters:
      value - The new value for this setting.
      The default is JsonSerializer.
      Returns:
      This object.

    • serializer

      public RestClient.Builder serializer(Serializer value)
      Serializer.

      Associates the specified Serializer with the HTTP client.

      The serializer is used to serialize POJOs into the HTTP request body.

      Notes:
      • When using this method that takes in a pre-instantiated serializer, the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class have no effect.
      Example:

      // Create a client that uses a predefined JSON serializer request bodies. RestClient client = RestClient .create() .serializer(JsonSerializer.DEFAULT_READABLE) .build();

      Parameters:
      value - The new value for this setting.
      The default is JsonSerializer.
      Cannot be null.
      Returns:
      This object.

    • serializers

      public final SerializerSet.Builder serializers()
      Returns the serializer group sub-builder.
      Returns:
      The serializer group sub-builder.

    • serializers

      public RestClient.Builder serializers(Class<? extends Serializer>... value)
      Serializers.

      Associates the specified Serializers with the HTTP client.

      The serializer is used to serialize POJOs into the HTTP request body.

      The serializer that best matches the Content-Type header will be used to serialize the request body.
      If no Content-Type header is specified, the first serializer in the list will be used.

      Notes:
      • When using this method that takes in classes, the serializers can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.
      Example:

      // Create a client that uses JSON and XML transport for request bodies. RestClient client = RestClient .create() .serializers(JsonSerializer.class, XmlSerializer.class) .sortCollections() // Sort any collections being serialized. .build();

      Parameters:
      value - The new value for this setting.
      The default is JsonSerializer.
      Returns:
      This object.

    • serializers

      public RestClient.Builder serializers(Serializer... value)
      Serializers.

      Associates the specified Serializers with the HTTP client.

      The serializer is used to serialize POJOs into the HTTP request body.

      The serializer that best matches the Content-Type header will be used to serialize the request body.
      If no Content-Type header is specified, the first serializer in the list will be used.

      Notes:
      • When using this method that takes in a pre-instantiated serializers, the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class have no effect.
      Example:

      // Create a client that uses predefined JSON and XML serializers for request bodies. RestClient client = RestClient .create() .serializers(JsonSerializer.DEFAULT_READABLE, XmlSerializer.DEFAULT_READABLE) .build();

      Parameters:
      value - The new value for this setting.
      The default is JsonSerializer.
      Returns:
      This object.

    • serviceUnavailableRetryStrategy

      public RestClient.Builder serviceUnavailableRetryStrategy(ServiceUnavailableRetryStrategy serviceUnavailStrategy)
      Assigns ServiceUnavailableRetryStrategy instance.
      Parameters:
      serviceUnavailStrategy - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • skipEmptyFormData

      public RestClient.Builder skipEmptyFormData()
      Skip empty form data.

      When enabled, form data consisting of empty strings will be skipped on requests. Note that null values are already skipped.

      The Schema.skipIfEmpty() annotation overrides this setting.

      Returns:
      This object.

    • skipEmptyFormData

      public RestClient.Builder skipEmptyFormData(boolean value)
      Skip empty form data.

      When enabled, form data consisting of empty strings will be skipped on requests. Note that null values are already skipped.

      The Schema.skipIfEmpty() annotation overrides this setting.

      Parameters:
      value - The new value for this setting.
      The default is false.
      Returns:
      This object.

    • skipEmptyHeaderData

      public RestClient.Builder skipEmptyHeaderData()
      Skip empty header data.

      When enabled, headers consisting of empty strings will be skipped on requests. Note that null values are already skipped.

      The Schema.skipIfEmpty() annotation overrides this setting.

      Returns:
      This object.

    • skipEmptyHeaderData

      public RestClient.Builder skipEmptyHeaderData(boolean value)
      Skip empty header data.

      When enabled, headers consisting of empty strings will be skipped on requests. Note that null values are already skipped.

      The Schema.skipIfEmpty() annotation overrides this setting.

      Parameters:
      value - The new value for this setting.
      The default is false.
      Returns:
      This object.

    • skipEmptyQueryData

      public RestClient.Builder skipEmptyQueryData()
      Skip empty query data.

      When enabled, query parameters consisting of empty strings will be skipped on requests. Note that null values are already skipped.

      The Schema.skipIfEmpty() annotation overrides this setting.

      Returns:
      This object.

    • skipEmptyQueryData

      public RestClient.Builder skipEmptyQueryData(boolean value)
      Skip empty query data.

      When enabled, query parameters consisting of empty strings will be skipped on requests. Note that null values are already skipped.

      The Schema.skipIfEmpty() annotation overrides this setting.

      Parameters:
      value - The new value for this setting.
      The default is false.
      Returns:
      This object.

    • sortCollections

      public RestClient.Builder sortCollections()
      Serializer configuration property:  Sort arrays and collections alphabetically.

      When enabled, copies and sorts the contents of arrays and collections before serializing them.

      Note that this introduces a performance penalty since it requires copying the existing collection.

      Example:

      // Create a REST client with JSON serializer that sorts arrays and collections before serialization. RestClient client = RestClient .create() .json() .sortCollections() .build(); // An unsorted array String[] array = {"foo","bar","baz"} // Request body will contain: ["bar","baz","foo"] client .post("http://localhost:10000/foo", array) .run();

      See Also:
      Returns:
      This object.

    • sortMaps

      public RestClient.Builder sortMaps()
      Serializer configuration property:  Sort maps alphabetically.

      When enabled, copies and sorts the contents of maps by their keys before serializing them.

      Note that this introduces a performance penalty.

      Example:

      // Create a REST client with JSON serializer that sorts maps before serialization. RestClient client = RestClient .create() .json() .sortMaps() .build(); // An unsorted map. AMap map = AMap.of("foo",1,"bar",2,"baz",3); // Request body will contain: {"bar":2,"baz":3,"foo":1} client .post("http://localhost:10000/foo", map) .run();

      See Also:
      Returns:
      This object.

    • sortProperties

      public RestClient.Builder sortProperties()
      Description copied from class: BeanContextable.Builder
      Sort bean properties.

      When enabled, all bean properties will be serialized and access in alphabetical order. Otherwise, the natural order of the bean properties is used which is dependent on the JVM vendor. On IBM JVMs, the bean properties are ordered based on their ordering in the Java file. On Oracle JVMs, the bean properties are not ordered (which follows the official JVM specs).

      this setting is disabled by default so that IBM JVM users don't have to use @Bean annotations to force bean properties to be in a particular order and can just alter the order of the fields/methods in the Java file.

      Example:

      // A bean with 3 properties. public class MyBean { public String c = "1"; public String b = "2"; public String a = "3"; } // Create a serializer that sorts bean properties. WriterSerializer serializer = JsonSerializer .create() .sortProperties() .build(); // Produces: {"a":"3","b":"2","c":"1"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Bean.sort() annotation can also be used to sort properties on just a single class.
      See Also:
      Overrides:
      sortProperties in class BeanContextable.Builder
      Returns:
      This object.

    • sortProperties

      public RestClient.Builder sortProperties(Class<?>... on)
      Description copied from class: BeanContextable.Builder
      Sort bean properties.

      Same as BeanContextable.Builder.sortProperties() but allows you to specify individual bean classes instead of globally.

      Example:

      // A bean with 3 properties. public class MyBean { public String c = "1"; public String b = "2"; public String a = "3"; } // Create a serializer that sorts properties on MyBean. WriterSerializer serializer = JsonSerializer .create() .sortProperties(MyBean.class) .build(); // Produces: {"a":"3","b":"2","c":"1"} String json = serializer.serialize(new MyBean());

      See Also:
      Overrides:
      sortProperties in class BeanContextable.Builder
      Parameters:
      on - The bean classes to sort properties on.
      Cannot contain null values.
      Returns:
      This object.

    • sq

      public RestClient.Builder sq()
      WriterSerializer configuration property:  Quote character.

      Specifies to use single quotes for quoting attributes and values.

      Notes:
      • This setting does not apply to the RDF serializers.
      Example:

      // Create a REST client with JSON serializer that uses single quotes. RestClient client = RestClient .create() .json() .sq() .build(); // A bean with a single property public class MyBean { public String foo = "bar"; } // Request body will contain: {'foo':'bar'} client .post("http://localhost:10000/foo", new MyBean()) .run();

      See Also:
      Returns:
      This object.

    • sslContext

      public RestClient.Builder sslContext(SSLContext sslContext)
      Assigns SSLContext instance.
      Notes:
      Parameters:
      sslContext - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • sslHostnameVerifier

      public RestClient.Builder sslHostnameVerifier(HostnameVerifier hostnameVerifier)
      Assigns HostnameVerifier instance.
      Notes:
      Parameters:
      hostnameVerifier - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • sslSocketFactory

      public RestClient.Builder sslSocketFactory(LayeredConnectionSocketFactory sslSocketFactory)
      Assigns LayeredConnectionSocketFactory instance.
      Notes:
      Parameters:
      sslSocketFactory - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • stopClass

      public RestClient.Builder stopClass(Class<?> on, Class<?> value)
      Description copied from class: BeanContextable.Builder
      Identifies a stop class for the annotated class.

      Identical in purpose to the stop class specified by Introspector.getBeanInfo(Class, Class). Any properties in the stop class or in its base classes will be ignored during analysis.

      For example, in the following class hierarchy, instances of C3 will include property p3, but not p1 or p2.

      Example:

      public class C1 { public int getP1(); } public class C2 extends C1 { public int getP2(); } public class C3 extends C2 { public int getP3(); } // Create a serializer specifies a stop class for C3. WriterSerializer serializer = JsonSerializer .create() .stopClass(C3.class, C2.class) .build(); // Produces: {"p3":"..."} String json = serializer.serialize(new C3());

      Overrides:
      stopClass in class BeanContextable.Builder
      Parameters:
      on - The class on which the stop class is being applied.
      Cannot be null.
      value - The new value for this setting.
      Cannot be null.
      Returns:
      This object.

    • strict

      public RestClient.Builder strict()
      Parser configuration property:  Strict mode.

      When enabled, strict mode for the parser is enabled.

      Strict mode can mean different things for different parsers.

      Parser classStrict behavior
      All reader-based parsers When enabled, throws ParseExceptions on malformed charset input. Otherwise, malformed input is ignored.
      JsonParser When enabled, throws exceptions on the following invalid JSON syntax:
      • Unquoted attributes.
      • Missing attribute values.
      • Concatenated strings.
      • Javascript comments.
      • Numbers and booleans when Strings are expected.
      • Numbers valid in Java but not JSON (e.g. octal notation, etc...)
      Example:

      // Create a REST client with JSON parser using strict mode. RestClient client = RestClient .create() .json() .strict() .build(); // Try to parse some bad JSON. try { client .get("/pathToBadJson") .run() .getContent().as(Object.class); // Try to parse it. } catch (RestCallException e) { // Handle exception. }

      See Also:
      Returns:
      This object.

    • swap

      public <T, S> RestClient.Builder swap(Class<T> normalClass, Class<S> swappedClass, ThrowingFunction<T,S> swapFunction)
      Description copied from class: BeanContextable.Builder
      A shortcut for defining a FunctionalSwap.
      Example:

      // Create a serializer that performs a custom format for Date objects. WriterSerializer serializer = JsonSerializer .create() .swap(Date.class, String.class, x -> format(x)) .build();

      Overrides:
      swap in class BeanContextable.Builder
      Type Parameters:
      T - The object type being swapped out.
      S - The object type being swapped in.
      Parameters:
      normalClass - The object type being swapped out.
      Cannot be null.
      swappedClass - The object type being swapped in.
      Cannot be null.
      swapFunction - The function to convert the object.
      Cannot be null.
      Returns:
      This object.

    • swap

      public <T, S> RestClient.Builder swap(Class<T> normalClass, Class<S> swappedClass, ThrowingFunction<T,S> swapFunction, ThrowingFunction<S,T> unswapFunction)
      Description copied from class: BeanContextable.Builder
      A shortcut for defining a FunctionalSwap.
      Example:

      // Create a serializer that performs a custom format for Date objects. WriterSerializer serializer = JsonSerializer .create() .swap(Date.class, String.class, x -> format(x), x -> parse(x)) .build();

      Overrides:
      swap in class BeanContextable.Builder
      Type Parameters:
      T - The object type being swapped out.
      S - The object type being swapped in.
      Parameters:
      normalClass - The object type being swapped out.
      Cannot be null.
      swappedClass - The object type being swapped in.
      Cannot be null.
      swapFunction - The function to convert the object during serialization.
      Cannot be null.
      unswapFunction - The function to convert the object during parsing.
      Cannot be null.
      Returns:
      This object.

    • swaps

      public RestClient.Builder swaps(Class<?>... values)
      Description copied from class: BeanContextable.Builder
      Same as BeanContextable.Builder.swaps(Object...) except explicitly specifies class varargs to avoid compilation warnings.
      Overrides:
      swaps in class BeanContextable.Builder
      Parameters:
      values - The values to add to this setting.
      Values can consist of any of the following types:
      Cannot contain null values.
      Returns:
      This object.

    • swaps

      public RestClient.Builder swaps(Object... values)
      Description copied from class: BeanContextable.Builder
      Java object swaps.

      Swaps are used to "swap out" non-serializable classes with serializable equivalents during serialization, and "swap in" the non-serializable class during parsing.

      An example of a swap would be a Calendar object that gets swapped out for an ISO8601 string.

      Multiple swaps can be associated with a single class. When multiple swaps are applicable to the same class, the media type pattern defined by ObjectSwap.forMediaTypes() or @Swap(mediaTypes) are used to come up with the best match.

      Values can consist of any of the following types:

      • Any subclass of ObjectSwap.
      • Any instance of ObjectSwap.
      • Any surrogate class. A shortcut for defining a SurrogateSwap.
      • Any array or collection of the objects above.
      Example:

      // Sample swap for converting Dates to ISO8601 strings. public class MyDateSwap extends StringSwap<Date> { // ISO8601 formatter. private DateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ"); @Override public String swap(BeanSession session, Date date) { return format.format(date); } @Override public Date unswap(BeanSession session, String string, ClassMeta hint) throws Exception { return format.parse(string); } } // Sample bean with a Date field. public class MyBean { public Date date = new Date(112, 2, 3, 4, 5, 6); } // Create a serializer that uses our date swap. WriterSerializer serializer = JsonSerializer .create() .swaps(MyDateSwap.class) .build(); // Produces: {"date":"2012-03-03T04:05:06-0500"} String json = serializer.serialize(new MyBean()); // Create a serializer that uses our date swap. ReaderParser parser = JsonParser .create() .swaps(MyDateSwap.class) .build(); // Use our parser to parse a bean. MyBean bean = parser.parse(json, MyBean.class);

      Notes:
      • The @Swap annotation can also be used on classes to identify swaps for the class.
      • The @Swap annotation can also be used on bean methods and fields to identify swaps for values of those bean properties.
      See Also:
      Overrides:
      swaps in class BeanContextable.Builder
      Parameters:
      values - The values to add to this setting.
      Values can consist of any of the following types:
      • Any subclass of ObjectSwap.
      • Any surrogate class. A shortcut for defining a SurrogateSwap.
      • Any array/collection/stream of the objects above.

      Cannot contain null values.
      Returns:
      This object.

    • targetAuthenticationStrategy

      public RestClient.Builder targetAuthenticationStrategy(AuthenticationStrategy targetAuthStrategy)
      Assigns AuthenticationStrategy instance for target host authentication.
      Parameters:
      targetAuthStrategy - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • timeZone

      public RestClient.Builder timeZone(TimeZone value)
      Description copied from class: BeanContextable.Builder
      Context configuration property:  TimeZone.

      Specifies the default time zone for serializer and parser sessions when not specified via BeanSession.Builder.timeZone(TimeZone). Typically used for POJO swaps that need to deal with timezones such as swaps that convert Date and Calendar objects to strings by accessing it via the session passed into the ObjectSwap.swap(BeanSession, Object) and ObjectSwap.unswap(BeanSession, Object, ClassMeta, String) methods.

      Example:

      // Define a POJO swap that skips serializing beans if the time zone is GMT. public class MyBeanSwap extends StringSwap<MyBean> { @Override public String swap(BeanSession session, MyBean bean) throws Exception { if (session.getTimeZone().equals(TimeZone.GMT)) return null; return bean.toString(); } } // Create a serializer that uses GMT if the timezone is not specified in the session args. WriterSerializer serializer = JsonSerializer .create() .timeZone(TimeZone.GMT) .build();

      See Also:
      Overrides:
      timeZone in class BeanContextable.Builder
      Parameters:
      value - The new value for this property.
      Can be null (timezone will not be set, defaults to system timezone).
      Returns:
      This object.

    • trimEmptyCollections

      public RestClient.Builder trimEmptyCollections()
      Serializer configuration property:  Trim empty lists and arrays.

      When enabled, empty lists and arrays will not be serialized.

      Note that enabling this setting has the following effects on parsing:

      • Map entries with empty list values will be lost.
      • Bean properties with empty list values will not be set.
      Example:

      // Create a serializer that skips empty arrays and collections. WriterSerializer serializer = JsonSerializer .create() .trimEmptyCollections() .build(); // A bean with a field with an empty array. public class MyBean { public String[] foo = {}; } // Request body will contain: {} client .post("http://localhost:10000/foo", new MyBean()) .run();

      See Also:
      Returns:
      This object.

    • trimEmptyMaps

      public RestClient.Builder trimEmptyMaps()
      Serializer configuration property:  Trim empty maps.

      When enabled, empty map values will not be serialized to the output.

      Note that enabling this setting has the following effects on parsing:

      • Bean properties with empty map values will not be set.
      Example:

      // Create a REST client with JSON serializer that skips empty maps. RestClient client = RestClient .create() .json() .trimEmptyMaps() .build(); // A bean with a field with an empty map. public class MyBean { public AMap foo = AMap.of(); } // Request body will contain: {} client .post("http://localhost:10000/foo", new MyBean()) .run();

      See Also:
      Returns:
      This object.

    • trimStringsOnRead

      public RestClient.Builder trimStringsOnRead()
      Parser configuration property:  Trim parsed strings.

      When enabled, string values will be trimmed of whitespace using String.trim() before being added to the POJO.

      Example:

      // Create a REST client with JSON parser with trim-strings enabled. RestClient client = RestClient .create() .json() .trimStringsOnRead() .build(); // Try to parse JSON containing {" foo ":" bar "}. Map<String,String> map = client .get("/pathToJson") .run() .getContent().as(HashMap.class, String.class, String.class); // Make sure strings are trimmed. assertEquals("bar", map.get("foo"));

      See Also:
      Returns:
      This object.

    • trimStringsOnWrite

      public RestClient.Builder trimStringsOnWrite()
      Serializer configuration property:  Trim strings.

      When enabled, string values will be trimmed of whitespace using String.trim() before being serialized.

      Example:

      // Create a REST client with JSON serializer that trims strings before serialization. RestClient client = RestClient .create() .json() .trimStrings() .build(); // A map with space-padded keys/values AMap map = AMap.of(" foo ", " bar "); // Request body will contain: {"foo":"bar"} client .post("http://localhost:10000/foo", map) .run();

      See Also:
      Returns:
      This object.

    • type

      public RestClient.Builder type(Class<? extends Context> value)
      Description copied from class: Context.Builder
      Associates a context class with this builder.

      This is the type of object that this builder creates when the Context.Builder.build() method is called.

      By default, it's the outer class of where the builder class is defined.

      If null is set, Context.Builder.build() will throw an exception. The default constructor automatically sets this to the outer class, so null should only be set explicitly if you want to override the default.

      Overrides:
      type in class BeanContextable.Builder
      Parameters:
      value - The context class that this builder should create.
      Can be null (will cause Context.Builder.build() to throw an exception).
      Returns:
      This object.

    • typeName

      public RestClient.Builder typeName(Class<?> on, String value)
      Description copied from class: BeanContextable.Builder
      An identifying name for this class.

      The name is used to identify the class type during parsing when it cannot be inferred through reflection. For example, if a bean property is of type Object, then the serializer will add the name to the output so that the class can be determined during parsing.

      It is also used to specify element names in XML.

      Example:

      // Use _type='mybean' to identify this bean. public class MyBean {...} // Create a serializer and specify the type name.. WriterSerializer serializer = JsonSerializer .create() .typeName(MyBean.class, "mybean") .build(); // Produces: {"_type":"mybean",...} String json = serializer.serialize(new MyBean());

      Notes:
      See Also:
      Overrides:
      typeName in class BeanContextable.Builder
      Parameters:
      on - The class the type name is being defined on.
      value - The new value for this setting.
      Cannot be null.
      Returns:
      This object.

    • typePropertyName

      public RestClient.Builder typePropertyName(Class<?> on, String value)
      Description copied from class: BeanContextable.Builder
      Bean type property name.

      Same as BeanContextable.Builder.typePropertyName(String) except targets a specific bean class instead of globally.

      Example:

      // POJOs with @Bean(name) annotations. @Bean(typeName="foo") public class Foo {...} @Bean(typeName="bar") public class Bar {...} // A bean with a field with an indeterminate type. public class MyBean { public Object mySimpleField; } // Create a serializer that uses 't' instead of '_type' for dictionary names. WriterSerializer serializer = JsonSerializer .create() .typePropertyName(MyBean.class, "t") .dictionary(Foo.class, Bar.class) .build(); // Produces "{mySimpleField:{t:'foo',...}}". String json = serializer.serialize(new MyBean());

      See Also:
      Overrides:
      typePropertyName in class BeanContextable.Builder
      Parameters:
      on - The class the type property name applies to.
      value - The new value for this setting.
      The default is "_type".
      Cannot be null.
      Returns:
      This object.

    • typePropertyName

      public RestClient.Builder typePropertyName(String value)
      Description copied from class: BeanContextable.Builder
      Bean type property name.

      This specifies the name of the bean property used to store the dictionary name of a bean type so that the parser knows the data type to reconstruct.

      Example:

      // POJOs with @Bean(name) annotations. @Bean(typeName="foo") public class Foo {...} @Bean(typeName="bar") public class Bar {...} // Create a serializer that uses 't' instead of '_type' for dictionary names. WriterSerializer serializer = JsonSerializer .create() .typePropertyName("t") .dictionary(Foo.class, Bar.class) .build(); // Create a serializer that uses 't' instead of '_type' for dictionary names. ReaderParser parser = JsonParser .create() .typePropertyName("t") .dictionary(Foo.class, Bar.class) .build(); // A bean with a field with an indeterminate type. public class MyBean { public Object mySimpleField; } // Produces "{mySimpleField:{t:'foo',...}}". String json = serializer.serialize(new MyBean()); // Parse bean. MyBean bean = parser.parse(json, MyBean.class);

      See Also:
      Overrides:
      typePropertyName in class BeanContextable.Builder
      Parameters:
      value - The new value for this setting.
      The default is "_type".
      Cannot be null.
      Returns:
      This object.

    • universal

      public RestClient.Builder universal()
      Convenience method for specifying all available transmission types.

      All basic Juneau serializers will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      • The serializers can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      All basic Juneau parsers will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parsers can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header must be set via headers(), or per-request via RestRequest.header(Header) in order for the correct parser to be selected.

      Content-Type request header must be set via headers(), or per-request via RestRequest.header(Header) in order for the correct serializer to be selected.

      Similar to calling json().json5().html().xml().uon().urlEnc().openApi().msgPack().plainText().

      Example:

      // Construct a client that uses universal marshalling. RestClient client = RestClient.create().universal().build();

      Returns:
      This object.

    • uon

      public RestClient.Builder uon()
      Convenience method for specifying UON as the marshalling transmission media type.

      UON is Url-Encoding Object notation that is equivalent to JSON but suitable for transmission as URL-encoded query and form post values.

      UonSerializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      • The serializer can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      UonParser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header will be set to "text/uon" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Content-Type request header will be set to "text/uon" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as json() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(UonSerializer.class).parser(UonParser.class).

      Example:

      // Construct a client that uses UON marshalling. RestClient client = RestClient.create().uon().build();

      Returns:
      This object.

    • uriContext

      public RestClient.Builder uriContext(UriContext value)
      Serializer configuration property:  URI context bean.

      Bean used for resolution of URIs to absolute or root-relative form.

      Example:

      // Our URI contextual information. String authority = "http://localhost:10000"; String contextRoot = "/myContext"; String servletPath = "/myServlet"; String pathInfo = "/foo"; // Create a UriContext object. UriContext uriContext = new UriContext(authority, contextRoot, servletPath, pathInfo); // Create a REST client with JSON serializer and associate our context. RestClient client = RestClient .create() .json() .uriContext(uriContext) .uriRelativity(RESOURCE) // Assume relative paths are relative to servlet. .uriResolution(ABSOLUTE) // Serialize URIs as absolute paths. .build(); // A relative URI URI uri = new URI("bar"); // Request body will contain: "http://localhost:10000/myContext/myServlet/foo/bar" client .post("http://localhost:10000/foo", uri) .run();

      See Also:
      Parameters:
      value - The new value for this property.
      Cannot be null.
      Returns:
      This object.

    • uriRelativity

      public RestClient.Builder uriRelativity(UriRelativity value)
      Serializer configuration property:  URI relativity.

      Defines what relative URIs are relative to when serializing any of the following:

      • URI
      • URL
      • Properties and classes annotated with @Uri

      See uriContext(UriContext) for examples.

      See Also:
      Parameters:
      value - The new value for this property.
      The default is UriRelativity.RESOURCE
      Cannot be null.
      Returns:
      This object.

    • uriResolution

      public RestClient.Builder uriResolution(UriResolution value)
      Serializer configuration property:  URI resolution.

      Defines the resolution level for URIs when serializing any of the following:

      • URI
      • URL
      • Properties and classes annotated with @Uri

      See uriContext(UriContext) for examples.

      See Also:
      Parameters:
      value - The new value for this property.
      The default is UriResolution.NONE
      Cannot be null.
      Returns:
      This object.

    • urlEnc

      public RestClient.Builder urlEnc()
      Convenience method for specifying URL-Encoding as the marshalling transmission media type.

      UrlEncodingSerializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      UrlEncodingParser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header will be set to "application/x-www-form-urlencoded" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Content-Type request header will be set to "application/x-www-form-urlencoded" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as json() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(UrlEncodingSerializer.class).parser(UrlEncodingParser.class).

      Example:

      // Construct a client that uses URL-Encoded marshalling. RestClient client = RestClient.create().urlEnc().build();

      Returns:
      This object.

    • urlEncodingSerializer

      public final UrlEncodingSerializer.Builder urlEncodingSerializer()
      Returns the URL-encoding serializer sub-builder.
      Returns:
      The URL-encoding serializer sub-builder.

    • useEnumNames

      public RestClient.Builder useEnumNames()
      Description copied from class: BeanContextable.Builder
      Use enum names.

      When enabled, enums are always serialized by name, not using Object.toString().

      Example:

      // Create a serializer with debug enabled. WriterSerializer serializer = JsonSerializer .create() .useEnumNames() .build(); // Enum with overridden toString(). // Will be serialized as ONE/TWO/THREE even though there's a toString() method. public enum Option { ONE(1), TWO(2), THREE(3); private int value; Option(int value) { this.value = value; } @Override public String toString() { return String.valueOf(value); } }

      See Also:
      Overrides:
      useEnumNames in class BeanContextable.Builder
      Returns:
      This object.

    • useJavaBeanIntrospector

      public RestClient.Builder useJavaBeanIntrospector()
      Description copied from class: BeanContextable.Builder
      Use Java Introspector.

      Using the built-in Java bean introspector will not pick up fields or non-standard getters/setters.
      Most @Bean annotations will be ignored.

      Example:

      // Create a serializer that only uses the built-in java bean introspector for finding properties. WriterSerializer serializer = JsonSerializer .create() .useJavaBeanIntrospector() .build();

      See Also:
      Overrides:
      useJavaBeanIntrospector in class BeanContextable.Builder
      Returns:
      This object.

    • userTokenHandler

      public RestClient.Builder userTokenHandler(UserTokenHandler userTokenHandler)
      Assigns UserTokenHandler instance.
      Notes:
      Parameters:
      userTokenHandler - New property value.
      Can be null (value will not be set, default behavior will be used).
      Returns:
      This object.
      See Also:

    • useSystemProperties

      public RestClient.Builder useSystemProperties()
      Use system properties when creating and configuring default implementations.
      Returns:
      This object.
      See Also:

    • useWhitespace

      public RestClient.Builder useWhitespace()
      WriterSerializer configuration property:  Use whitespace.

      When enabled, whitespace is added to the output to improve readability.

      Example:

      // Create a REST client with JSON serializer with whitespace enabled. RestClient client = RestClient .create() .json() .useWhitespace() .build(); // A bean with a single property public class MyBean { public String foo = "bar"; } // Request body will contain: {\n\t"foo": "bar"\n\}\n client .post("http://localhost:10000/foo", new MyBean()) .run();

      See Also:
      Returns:
      This object.

    • ws

      public RestClient.Builder ws()
      WriterSerializer configuration property:  Use whitespace.

      When enabled, whitespace is added to the output to improve readability.

      Example:

      // Create a REST client with JSON serializer with whitespace enabled. RestClient client = RestClient .create() .json() .ws() .build(); // A bean with a single property public class MyBean { public String foo = "bar"; } // Request body will contain: {\n\t"foo": "bar"\n\}\n client .post("http://localhost:10000/foo", new MyBean()) .run();

      See Also:
      Returns:
      This object.

    • xml

      public RestClient.Builder xml()
      Convenience method for specifying XML as the marshalling transmission media type.

      XmlSerializer will be used to serialize POJOs to request bodies unless overridden per request via RestRequest.serializer(Serializer).

      • The serializer can be configured using any of the serializer property setters (e.g. sortCollections()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      XmlParser will be used to parse POJOs from response bodies unless overridden per request via RestRequest.parser(Parser).

      • The parser can be configured using any of the parser property setters (e.g. strict()) or bean context property setters (e.g. swaps(Class...)) defined on this builder class.

      Accept request header will be set to "text/xml" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Content-Type request header will be set to "text/xml" unless overridden via headers(), or per-request via RestRequest.header(Header).

      Can be combined with other marshaller setters such as json() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(XmlSerializer.class).parser(XmlParser.class).

      Example:

      // Construct a client that uses XML marshalling. RestClient client = RestClient.create().xml().build();

      Returns:
      This object.

    • createCallHandler

      protected BeanCreator<RestCallHandler> createCallHandler()
      Creates the creator for the rest call handler.

      Subclasses can override this method to provide their own implementation.

      The default behavior creates a bean creator initialized to return a BasicRestCallHandler.

      Returns:
      The creator for the rest call handler.
      See Also:

    • createConnectionManager

      protected HttpClientConnectionManager createConnectionManager()
      Creates the HttpClientConnectionManager returned by createConnectionManager().

      Subclasses can override this method to provide their own connection manager.

      The default implementation returns an instance of a PoolingHttpClientConnectionManager if pooled() was called or BasicHttpClientConnectionManager if not..

      Example:

      // A Builder that provides it's own customized HttpClientConnectionManager. public class MyBuilder extends Builder { @Override protected HttpClientConnectionManager createConnectionManager() { return new PoolingHttpClientConnectionManager(); } } // Instantiate. RestClient client = new MyBuilder().build();

      Returns:
      The HTTP client builder to use to create the HTTP client.

    • createFormData

      protected PartList createFormData()
      Creates the builder for the form data list.

      Subclasses can override this method to provide their own implementation.

      The default behavior creates an empty builder.

      Returns:
      The query data list builder.
      See Also:

    • createHeaderData

      protected HeaderList createHeaderData()
      Creates the builder for the header list.

      Subclasses can override this method to provide their own implementation.

      The default behavior creates an empty builder.

      Returns:
      The header list builder.
      See Also:

    • createHttpClient

      protected CloseableHttpClient createHttpClient()
      Creates an instance of an HttpClient to be used to handle all HTTP communications with the target server.

      This HTTP client is used when the HTTP client is not specified through one of the constructors or the httpClient(CloseableHttpClient) method.

      Subclasses can override this method to provide specially-configured HTTP clients to handle stuff such as SSL/TLS certificate handling, authentication, etc.

      The default implementation returns an instance of HttpClient using the client builder returned by createHttpClientBuilder().

      Example:

      // A Builder that provides it's own customized HttpClient. public class MyBuilder extends Builder { @Override protected HttpClientBuilder createHttpClient() { return HttpClientBuilder.create().build(); } } // Instantiate. RestClient client = new MyBuilder().build();

      Returns:
      The HTTP client to use.

    • createHttpClientBuilder

      protected HttpClientBuilder createHttpClientBuilder()
      Creates an instance of an HttpClientBuilder to be used to create the HttpClient.

      Subclasses can override this method to provide their own client builder. The builder can also be specified using the httpClientBuilder(HttpClientBuilder) method.

      Example:

      // A Builder that provides it's own customized HttpClientBuilder. public class MyBuilder extends Builder { @Override protected HttpClientBuilder createHttpClientBuilder() { return HttpClientBuilder.create(); } } // Instantiate. RestClient client = new MyBuilder().build();

      Returns:
      The HTTP client builder to use to create the HTTP client.

    • createParsers

      protected ParserSet.Builder createParsers()
      Instantiates the parser group sub-builder.
      Returns:
      A new parser group sub-builder.

    • createPartParser

      protected HttpPartParser.Creator createPartParser()
      Instantiates the part parser sub-builder.
      Returns:
      A new part parser sub-builder.

    • createPartSerializer

      protected HttpPartSerializer.Creator createPartSerializer()
      Instantiates the part serializer sub-builder.
      Returns:
      A new part serializer sub-builder.

    • createPathData

      protected PartList createPathData()
      Creates the builder for the path data list.

      Subclasses can override this method to provide their own implementation.

      The default behavior creates an empty builder.

      Returns:
      The query data list builder.
      See Also:

    • createQueryData

      protected PartList createQueryData()
      Creates the builder for the query data list.

      Subclasses can override this method to provide their own implementation.

      The default behavior creates an empty builder.

      Returns:
      The query data list builder.
      See Also:

    • createSerializers

      protected SerializerSet.Builder createSerializers()
      Instantiates the serializer group sub-builder.
      Returns:
      A new serializer group sub-builder.

    • createUrlEncodingSerializer

      protected UrlEncodingSerializer.Builder createUrlEncodingSerializer()
      Instantiates the URL-encoding serializer sub-builder.
      Returns:
      A new URL-encoding serializer sub-builder.