With this short tutorial you will learn how to use TERYT Service in a project. Note that this tutorial is simplified and you will probably want to introduce some improvements respecting specificity of your project.
Lets assume that you need to create web application that edits object with address described with TERYT system. You want to create a screen like this:
So you need a form service that will provide values for the select boxes with voivodships, poviats, communes and cities.
Add TERYT Client to application
The first step is to add TERYT Client of your choice (REST or SOAP) to your application. The easiest way to do this is to use declarative way, using Service Client Configurator module. Add this module JAR and appropriate client JAR to project (e.g. with Maven), put configuration of your Client in XML file and use XmlTerytServiceConfigurator class from module to create the Service from that XML:
<some-node> <configuration-class>some.package.ClassName</configuration-class> <configuration> ... here goes configuration data ... </configuration> </some-node>
For example to use Soap client use:
<some-node> <configuration-class>pl.frati.teryt.service.client.TerytServiceClientWsConfiguration</configuration-class> <configuration> <webservice-url>http://example.com/webservices</webservice-url> </configuration> </some-node>
Note that SOAP Client JAR must be available on classpath.
Consult Service Client Configurator module site to learn more about XML configurator tool.
Possibly you will not like to stick with exactly one client implementation (SOAP/REST/etc.) thus Service Client API is provided so actual implementation could be easily replaced (especially with test implementation see below).
Implement form service methods
Now use your Service Client in service methods to obtain voivodships, poviats, communes and cities lists from TERYT Service. Note that it is preferred to use Service Client API so client implementation can be easily replaced.
Test your form service methods
Good practice is to test what we write :). For tests that are rather unit tests you usually want some kind of mocked services. In such case simply use Test Service. Add this module (eg. using Maven) and use TerytTestServiceConfiguration in your XML Client configuration file used by unit test.
<some-node> <configuration-class>pl.frati.teryt.service.test.TerytTestServiceConfiguration</configuration-class> </some-node>
This way a test client will be created with no changes in your implementation. You can use test data provided by Test Service to test your form service methods.