This is a Java language binding (wrapper) to the Open311 GeoReport v2 REST API (current version:
0.0.4). You can check the library site if you want to check the javadocs, test coverage, etc.
The main features are:
- Admits endpoints whose CA is not recognized by Java
- Compatible with Android (transparently, it selects the correct components from your execution environment)
- Compatible with some non-standard GeoReport servers.
If you find any problem or miss any feature, just open an issue.
If you are interested about new features or the development process please check this blog.
How to get the library
Add it as a dependency
The easiest way to start using the library is to add the dependency to your project dependency manager system. The library is currently avaliable in the Maven central repository, which makes it compatible with tools such as:
Below, an example using Maven.
<dependency> <groupId>org.codeforamerica.open311</groupId> <artifactId>jreport</artifactId> <version>0.0.4</version> </dependency>
There are many links in the Maven central repository page, and you can find the
.jar file (with its sources and javadocs). Please, note that this
.jar does not contains its dependencies, so it will not work unless you attach them too.
In order to compile and test this project you should have Maven installed in your system.
# Clone this repository git clone https://github.com/codeforamerica/open311_java.git cd open311_java # The following commands are independent. Execute which you need (probably the last one). # Compile the project (and download dependencies) mvn compile # Execute tests mvn test # Execute tests with cobertura analysis mvn cobertura:cobertura # Generate the .jar without dependencies mvn package # Generate the .jar with dependencies mvn assembly:assembly
You may have problems if you are using an old version of
git since one of the executed commands is
git clone --recursive and it doesn't work with its oldest versions. Please, update your
git in that case.
mvn cobertura:coberturawill write its output in
target/site/cobertura/, open the
index.htmlfile to check it.
mvn packagewill output the
mvn assembly:assemblywill output the
Build a wrapper
- Specifying the desired city and type of the endpoint (production, test...). The wrapper will get the most suitable endpoint and data interchange format for you.
- Specifying the url of endpoint, the jurisdiction_id parameter and the data interchange format. It is your responsibility to check if the format you desire is supported.
// From the city (EndpointType.PRODUCTION is selected by default) APIWrapper wrapper = new APIWrapperFactory(City.SAN_FRANCISCO).build(); // From the city, test endpoint. APIWrapper wrapper = new APIWrapperFactory(City.SAN_FRANCISCO, EndpointType.TEST).build(); // From the url of the endpoint APIWrapper wrapper = new APIWrapperFactory("https://www.myendpointurl.com/").build(); // From the url of the endpoint, the jurisdiction_id, and the data interchange format APIWrapper wrapper = new APIWrapperFactory("https://www.myendpointurl.com/", "myjurisdictionId", Format.JSON).build(); // With the api key wrapper = new APIWrapperFactory(City.SAN_FRANCISCO).setApiKey("your api key").build(); // Without caching data and the api key wrapper = new APIWrapperFactory(City.SAN_FRANCISCO).setCache(new NoCache()). setApiKey("your api key").build();
Check all the possible parameters and constructors of the
APIWrapperFactory in its documentation page.
// GET service list List<Service> listOfServices = wrapper.getServiceList(); // GET service definition ServiceDefinition definition = wrapper.getServiceDefinition("serviceCode"); // POST service request POSTServiceRequestResponse response = wrapper.postServiceRequest( new POSTServiceRequestData("serviceCode", addressId, listOfattributes)); // GET service_request_id from a token ServiceRequestIdResponse serviceRequestIdresponse = wrapper.getServiceRequestIdFromToken("token"); // GET service requests List<ServiceRequest> serviceRequests = wrapper.getServiceRequests( new GETServiceRequestsFilter().setStatus(Status.OPEN)); // GET service request ServiceRequest serviceRequest = wrapper.getServiceRequest("serviceRequestId");
It is worth it to check the documentation and find all the possible parameters of the
This library tries to save some responses for a certain time in order to avoid expensive network operations.
- In a regular Java application, it is activated by default.
- If you do not want to cache anything:
factory = new APIWrapperFactory().setCache(new NoCache());
- Using an Android app:
factory = new APIWrapperFactory().setCache(AndroidCache.getInstance(getApplicationContext()));
- Using a special platform which doesn't allow to create or write to files: Extend the AbstractCache class and
factory = new APIWrapperFactory().setCache(new YourCacheImplementation());
In case you want to delete the cache:
- Use your wrapper's cache:
- Get your platform's cache:
Please, note that when you delete the cache you will delete ALL the cached data.
Some of the endpoints could have SSL certificates which signature won't be recognize by Java. Up to now, the HTTP client used by this library ignores those certificate signature problems so it is your responsibility to make sure that you are providing a secure url.