https://github.com/exabrial/form-binding
Bind Java objects to URL Encoded Forms similar to JSON-B or JAX-B, and a JAX-RS Form Encoding MessageBodyWriter/Reader
https://github.com/exabrial/form-binding
annotations binding converter encoding form http java java-ee java-spi jax-rs parameters rest url-encoding x-www-form-urlencoded
Last synced: 1 day ago
JSON representation
Bind Java objects to URL Encoded Forms similar to JSON-B or JAX-B, and a JAX-RS Form Encoding MessageBodyWriter/Reader
- Host: GitHub
- URL: https://github.com/exabrial/form-binding
- Owner: exabrial
- License: apache-2.0
- Created: 2019-11-13T22:32:50.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2025-05-28T18:07:19.000Z (8 months ago)
- Last Synced: 2025-07-05T11:16:51.895Z (6 months ago)
- Topics: annotations, binding, converter, encoding, form, http, java, java-ee, java-spi, jax-rs, parameters, rest, url-encoding, x-www-form-urlencoded
- Language: Java
- Homepage:
- Size: 75.2 KB
- Stars: 4
- Watchers: 5
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Form Binding
I looked far and wide and was surprised that there was no annotation based way to bind Form URL Encoded string to a Java Object. Think of this project like JAX-B or JSON-B, but for Form URL Encoding.
Wouldn't it be nice to create this form:
```
key=AGreatSuccess&anInt=42
```
From this object:
```
public class TestObject {
private String key = "AGreatSuccess";
private int anInt = 42;
}
```
With on line of code:
```
final String form = writer.write(new TestObject());
```
Yes. Yes it would. Oh and there's a JAX-RS integration: MessageBodyReader and MessageBodyWriter that produces/consumes `application/x-www-form-urlencoded`!
## License
All files are Licensed Apache Source License 2.0. Please consider contributing back any changes you may make, thanks!
## Usage
There are two parts, and API jar and a implementation jar. Include the API jar in your project as a compile dependency, and the implementation jar as a runtime dependency. Annotate your fields (or don't, the default behavior uses the field name and looks at any fields not marked as transient). The Java SPI system will load the implementation for you.
Internally this project makes heavy use of Apache Bean Utils `ConvertUtils` to convert between strings and value types. You can even extend this behavior by implementing `FormBindingConverter` and packaging it as a Java SPI Service.
### Maven Coordinates
API Jar:
```
com.github.exabrial
form-binding-api
SEE THE RELEASES TAB FOR VERSION NUMBER
compile
```
Runtime Jar:
```
com.github.exabrial
form-binding
SEE THE RELEASES TAB FOR VERSION NUMBER
runtime
```
### Binding your classes
* The default behavior is to bind all of your fields that are not marked `@FormBindingTransient`
* If _any_ field is marked as a `@FormBindingParam`, only fields that are marked with `@FormBindingParam` will be serialized
* You can change the name of the parameter bound like this: `@FormBindingParam(paramName = "differentName")`
Example:
```
public class MixedAnnotations {
@FormBindingParam(paramName = "differentName")
private String heresAField = "Here's a field!!!";
@FormBindingTransient
private String ignoreMe = "Don't encode this!!";
private String heresANonAnnotatedField = "It shouldn't be included";
}
```
### Java Object -> Form URL Encoded String
```
FormBindingWriter writer = FormBinding.getWriter();
String form = writer.write(new MixedAnnotations());
```
Will produce:
```
differentName=Here%27s+a+field%21%21%21
```
### Form URL Encoded String -> Java Object
```
String input = "differentName=ConvertingBackToJavaObject";
MixedAnnotations mixedAnnotations = reader.read(input, MixedAnnotations.class);
```
On the returned object, `heresAField` the field will be set to: `ConvertingBackToJavaObject`
### Implementing your own converter
* Bean Utils does pretty good job with basic types, but if you have nested objects, you'll want to implement your own converter.
* Simply implement that `FormBindingConverter` interface, then put a file in `META-INF/services` named `com.github.exabrial.formbinding.FormBindingConverter`
* Inside this file, put the fully qualified classname of your custom implementation
* See https://github.com/exabrial/form-binding/tree/master/form-binding-test-module for an example
### JAX-RS
#### Maven Coordinates
```
com.github.exabrial
form-binding-jaxrs
SEE THE RELEASES TAB FOR VERSION NUMBER
compile
com.github.exabrial
form-binding
SEE THE RELEASES TAB FOR VERSION NUMBER
runtime
```
#### Server
* Accept forms easily without a ton of silly `@FormParam` annotations!
```
@ApplicationPath("/api/1.0")
public class RestApplication extends Application {
@Override
public Set> getClasses() {
return new HashSet>(Arrays.asList(new Class>[] { RestResource.class, FormBindingMessageBodyReader.class }));
}
}
```
```
@ApplicationScoped
@Path("/testObject")
@Consumes({ MediaType.APPLICATION_FORM_URLENCODED })
public class RestResource {
@POST
public void testObjectForm(TestObject testObject) {
System.out.println(testObject);
}
}
```
#### Client
* Post an http form to a URL without creating an intermediary MultiValuedMap or JAX-RS `javax.ws.rs.core.Form` class:
```
public void postTestObject(TestObject testObject) {
Client client = ClientBuilder.newClient();
client.register(FormBindingMessageBodyWriter.class);
client.target("http://example.com").path("testObject").request().post(Entity.entity(testObject, MediaType.APPLICATION_FORM_URLENCODED));
client.close();
}
```
* Read an `application/x-www-form-urlencoded` response back from a REST service!
```
public TestObject getTestObject() {
Client client = ClientBuilder.newClient();
client.register(FormBindingMessageBodyReader.class);
TestObject testObject = client.target("http://example.com").path("testObject").request().accept(MediaType.APPLICATION_FORM_URLENCODED).get(TestObject.class);
client.close();
return testObject;
}
```