Consuming a SOAP webservice over HTTPS

In the previous post, we talked about producing and consuming a SOAP web service here. This post will be a sequel to that post since recently I faced a similar issue during my project. In this post, we will talk about how to consume a SOAP web service over https. Since this will be a small post, we will not be posting any code on github.

Problem –

While consuming a SOAP web service which is behind SSL, if you don’t handle SSL certificates, you will run into following error


sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
 at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:387)
 at sun.security.validator.PKIXValidator.engineValidate(PKIXValidator.java:292)
 at sun.security.validator.Validator.validate(Validator.java:260)
 at sun.security.ssl.X509TrustManagerImpl.validate(X509TrustManagerImpl.java:324)
 at sun.security.ssl.X509TrustManagerImpl.checkTrusted(X509TrustManagerImpl.java:229)
 at sun.security.ssl.X509TrustManagerImpl.checkServerTrusted(X509TrustManagerImpl.java:124)
 at sun.security.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:1351)
 at sun.security.ssl.ClientHandshaker.processMessage(ClientHandshaker.java:156)
 at sun.security.ssl.Handshaker.processLoop(Handshaker.java:925)
 at sun.security.ssl.Handshaker.process_record(Handshaker.java:860)
 at sun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:1043)
 at sun.security.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1343)
 at sun.security.ssl.SSLSocketImpl.writeRecord(SSLSocketImpl.java:728)
 at sun.security.ssl.AppOutputStream.write(AppOutputStream.java:123)
 at sun.security.ssl.AppOutputStream.write(AppOutputStream.java:138)
 at SSLPoke.main(SSLPoke.java:31)
Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
 at sun.security.provider.certpath.SunCertPathBuilder.build(SunCertPathBuilder.java:145)
 at sun.security.provider.certpath.SunCertPathBuilder.engineBuild(SunCertPathBuilder.java:131)
 at java.security.cert.CertPathBuilder.build(CertPathBuilder.java:280)
 at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:382)
 ... 15 more

Solution –

Basically this error is happening if your SOAP web service is on SSL and the client is trying to connect to web service, web service doesn’t recognize the client and throws this error.

To resolve this error, you can download a SSL certificate from the server where you are hosting SOAP web service and import that certificate on your client machine’s keystore. In production environment, you should have a way to access this keystore when a call is made to the web service.

Let’s assume that our webservice from post is on SSL, like https://localhost:8943/benefits/endpoints/users.wsdl. If you access this URL in browser, you will be able to see the SSL certificate. Export this SSL certificate in base 64 format file, example sslcertificate.crt. Import this certificate in


keytool -import -alias sslcertificateofserver -keystore truststore.jks -storepass changeit -file sslcertificate.crt

Now, we will change the configuration class we wrote to configure web service components.


package com.betterjavacode.benefits.views;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.oxm.jaxb.Jaxb2Marshaller;

@Configuration
public class ClientAppConfig
{
   private Resource getKeyStore()
   {
      Environment.getProperty("betterjavacode.com.keystore");
   }

   private String getKeystorePassword()
   {
      Environment.getProperty("betterjavacode.com.keyStorePassword");
   }

   @Bean
   public Jaxb2Marshaller marshaller()
   {
     Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
     marshaller.setContextPath("com.betterjavacode.benefits.soap");
     return marshaller;
   }

   @Bean
    public UserClient userClient(Jaxb2Marshaller marshaller) {
        // WSDL URL - http://localhost:8080/benefits/endpoints/users.wsdl
        UserClient uc = new UserClient();
        uc.setDefaultUri("http://localhost:8080/benefits/endpoints/users.wsdl");
        uc.setMarshaller(marshaller);
        uc.setUnmarshaller(marshaller);

        FileInputStream fis = new FileInputStream(getKeyStore());
        KeyStore ks = KeyStore.getInstance("JKS");
        ks.load(fis, getKeyStorePassword().toCharArray());

        try {
            fis.close();
        } catch (IOException e) {
        }
        KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
        keyManagerFactory.init(ks, keyStorePassword.toCharArray());

        FileInputStream fisTS = new FileInputStream(getKeyStore());
        KeyStore ts = KeyStore.getInstance("JKS");
        ts.load(fisTS, trustStorePassword.toCharArray());

        try {
            fisTS.close();
        } catch(IOException e) {
        }
        TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
        trustManagerFactory.init(ts);

        HttpsUrlConnectionMessageSender messageSender = new HttpsUrlConnectionMessageSender();
        messageSender.setKeyManagers(keyManagerFactory.getKeyManagers());
        messageSender.setTrustManagers(trustManagerFactory.getTrustManagers());

        HostNameVerifier hv = new HostNameVerifier(){
           @Override
           public boolean verify(    String hostname,    SSLSession session){
                  return true;
           }
        }
        messageSender.setHostnameVerifier(hv);
        uc.setMessageSender(messageSender);
        return uc;
    }

This change should fix the error about PKIX path building failed. I will post the code for this article on github in next few days.

Conclusion –

In short, we showed how to consume a SOAP web service over SSL by adding keystore and truststore check during runtime.

Producing and Consuming SOAP Webservice with Spring Boot – Part V

In last few posts, we have covered following

  1. Spring Boot REST CRUD API – Part I
  2. Swagger Documentation for Spring Boot REST API – Part II
  3. Error Handling and logging in Spring Boot REST API – Part III
  4. Consuming RESTful Webservice – Part IV

In this post, we will describe how to create a SOAP webservice from our existing Spring Boot REST API. This SOAP webservice will provide us user data from the database which is we have connected through Spring-data in Spring REST API.

1. Requirements

  1. Eclipse Mars2
  2. Maven 3.1 and above
  3. Spring 1.4 and above
  4. Java 7
  5. Tomcat 8

2. SOAP Web Service

We will use our existing Spring Boot REST API to build an application that will act as a SOAP web service to provide users data. For a given user id, web service will return user data.

Let’s create a schema file in src/main/resources directory and maven will create java classes based on this schema file.


<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="https://betterjavacode.com/benefits/soap"
targetNamespace="https://betterjavacode.com/benefits/soap" elementFormDefault="qualified">
<xs:element name="getUserRequest">
<xs:complexType>
<xs:sequence>
<xs:element name="id" type="xs:int"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="getUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="user" type="tns:user"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="user">
<xs:sequence>
<xs:element name="id" type="xs:int"/>
<xs:element name="firstname" type="xs:string"/>
<xs:element name="middlename" type="xs:string"/>
<xs:element name="lastname" type="xs:string"/>
<xs:element name="username" type="xs:string"/>
<xs:element name="createdate" type="xs:date"/>
<xs:element name="jobtitle" type="xs:string"/>
<xs:element name="email" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:schema>

3. Update Maven dependencies

Now to generate classes from schema, we have to make sure we have all the right dependencies in our pom.xml. We will also add spring boot service dependency to create a SOAP web service.


<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.betterjavacode</groupId>
<artifactId>Benefits</artifactId>
<packaging>war</packaging>
<version>0.0.1-SNAPSHOT</version>
<name>Benefits Maven Webapp</name>
<url>http://maven.apache.org</url>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.4.2.RELEASE</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jersey2-jaxrs</artifactId>
<version>1.5.12</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-api</artifactId>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web-services</artifactId>
</dependency>
<dependency>
<groupId>wsdl4j</groupId>
<artifactId>wsdl4j</artifactId>
</dependency>
<dependency>
<groupId>javax.xml.bind</groupId>
<artifactId>jaxb-api</artifactId>
<version>2.1</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.3</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>2.6</version>
<configuration>
<warSourceDirectory>WebContent</warSourceDirectory>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>jaxb2-maven-plugin</artifactId>
<version>1.6</version>
<executions>
<execution>
<id>xjc</id>
<goals>
<goal>xjc</goal>
</goals>
</execution>
</executions>
<configuration>
<schemaDirectory>${project.basedir}/src/main/resources/</schemaDirectory>
<outputDirectory>${project.basedir}/src/main/java</outputDirectory>
<clearOutputDir>false</clearOutputDir>
<schemaLanguage>WSDL</schemaLanguage>
<generatePackage>com.betterjavacode.benefits.soap</generatePackage>
<forceRegenerate>true</forceRegenerate>
<scehmas>
<schema>
<url>http://localhost:8080/benefits/endpoints/users.wsdl</url>
</schema>
</scehmas>
</configuration>
</plugin>
</plugins>
<finalName>Benefits</finalName>
</build>
</project>

If we run the project with maven build now, the plugin jaxb2-maven-plugin will generate classes under com.betterjavacode.benefits.soap directory. It will also enable our wsdl SOAP url for users. This will generate following java objects

  • GetUserRequest
  • GetUserResponse
  • ObjectFactory
  • package-info
  • User

4. Defining the service

Next, we will define an interface for our service. This will look like below


package com.betterjavacode.benefits.services;

public interface UserAccountService

{

public com.betterjavacode.benefits.soap.User getUserDetails(int id);
}

Implementation of this service will be mapping out entity class User to generated class for soap service User. Using the id as a key to get user data from repository, we will map to soap service user. For post purposes, we will not show the implementation of this interface.

5. Creating the Service Endpoint

What is a service endpoint? When a SOAP request for defined URL is handled by Spring servlet, Spring servlet redirects that request to service endpoint. Service endpoint then processes that request to create a response. Our spring-boot-starter-web-services dependency will bring all the necessary classes for annotation purposes.


package com.betterjavacode.benefits.services.endpoints;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.ws.server.endpoint.annotation.Endpoint;
import org.springframework.ws.server.endpoint.annotation.PayloadRoot;
import org.springframework.ws.server.endpoint.annotation.RequestPayload;
import org.springframework.ws.server.endpoint.annotation.ResponsePayload;

import com.betterjavacode.benefits.services.UserAccountService;
import com.betterjavacode.benefits.soap.GetUserRequest;
import com.betterjavacode.benefits.soap.GetUserResponse;
import com.betterjavacode.benefits.soap.User;

@Endpoint
public class UserAccountServiceEndpoint

{

// private static final String TARGET_NAMESPACE =              "http://com/betterjavacode/benefits/webservices/useraccountservice";
private static final String TARGET_NAMESPACE =   "https://betterjavacode.com/benefits/soap";

@Autowired
private UserAccountService userAccountService;

@PayloadRoot(localPart = "getUserRequest", namespace = TARGET_NAMESPACE)
public @ResponsePayload GetUserResponse getUserRequest(@RequestPayload    GetUserRequest request)

{
GetUserResponse response = new GetUserResponse();
User user = userAccountService.getUserDetails(request.getId());
response.setUser(user);
return response;
}
}

@Endpoint annotation allows the class to be defined as service endpoint and included in @Component annotation for scanning. Make sure the namespace defined in this class matches with XSD schema definition. Otherwise, you can run into error for “No Endpoint defined for“.

6. Configuration

Next, we will configure our configuration class to generate wsdl endpoint. This configuration class will be annotated by @EnableWs to provide web service configuration.


package com.betterjavacode.benefits;

import org.springframework.boot.web.servlet.ServletRegistrationBean;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.springframework.ws.config.annotation.EnableWs;
import org.springframework.ws.config.annotation.WsConfigurerAdapter;
import org.springframework.ws.transport.http.MessageDispatcherServlet;
import org.springframework.ws.wsdl.wsdl11.DefaultWsdl11Definition;
import org.springframework.xml.xsd.SimpleXsdSchema;
import org.springframework.xml.xsd.XsdSchema;

@Configuration
@EnableWs
@ComponentScan("com.betterjavacode")
public class AppConfig extends WsConfigurerAdapter {

@Bean
public ServletRegistrationBean messageDispatcherServlet(ApplicationContext applicationContext) {
MessageDispatcherServlet servlet = new MessageDispatcherServlet();
servlet.setApplicationContext(applicationContext);

return new ServletRegistrationBean(servlet, "/benefits/endpoints/*");
}

@Bean(name = "users")
public DefaultWsdl11Definition defaultWsdl11Definition(XsdSchema usersSchema) {
DefaultWsdl11Definition wsdl11definition = new DefaultWsdl11Definition();
wsdl11definition.setPortTypeName("UserAccountService");
wsdl11definition.setLocationUri("/endpoints");
wsdl11definition.setTargetNamespace("http://com/betterjavacode/benefits/webservices/useraccountservice");
wsdl11definition.setSchema(usersSchema);
return wsdl11definition;
}

@Bean
public XsdSchema usersSchema() {
return new SimpleXsdSchema(new ClassPathResource("employees.xsd"));
}

}

Few important points about this configuration class are

  • MessageDispatcherServlet is a required servlet to dispatch web service messages. We set this servlet with a bean to handle the URL from which request will be coming.
  • DefaultWsdl11Definition creates SOAP for the given XSD schema
  • XsdSchema provides abstraction for our users XSD schema

7. Running the SOAP webservice

Now build our project with maven. Run the spring boot application through eclipse to start the embedded tomcat server. Once the tomcat server starts, if we access url http://localhost:8080/benefits/endpoints/users.wsdl

Output in the browser will be as below

wsdl endpoint

 

Here we showed how to create a simple SOAP webservice which we have combined with Spring Boot REST API service. We can also test this SOAP webservice using Soap UI, as shown in below screenshot

SoapUITest

8. Consuming the SOAP web service

In previous steps, we showed how to produce a SOAP web service, now we will show how to consume this SOAP web service programmatically.

8.1 Create a client class

Under package com.betterjavacode.benefits.views, define a class UserClient which will extend a WebServiceGatewaySupport class. WebServiceGatewaySupport class provides web service methods.


package com.betterjavacode.benefits.views;

import org.springframework.ws.client.core.support.WebServiceGatewaySupport;
import org.springframework.ws.soap.client.core.SoapActionCallback;

import com.betterjavacode.benefits.soap.GetUserRequest;
import com.betterjavacode.benefits.soap.GetUserResponse;

public class UserClient extends WebServiceGatewaySupport {

public GetUserResponse getUserById(int userid) {
GetUserRequest userrequest = new GetUserRequest();
userrequest.setId(userid);
GetUserResponse response = (GetUserResponse) getWebServiceTemplate().marshalSendAndReceive(userrequest, new SoapActionCallback("http://localhost:8080/benefits/endpoints/getUserResponse"));
return response;
}
}

8.2 Configure the client for Spring Bean support

We will configure Jaxb2Marshaller to support JAXB to set context path. This will help us marshal and unmarshal our xml request and response through.


package com.betterjavacode.benefits.views;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.oxm.jaxb.Jaxb2Marshaller;

@Configuration
public class ClientAppConfig {
@Bean
public Jaxb2Marshaller marshaller() {
Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
marshaller.setContextPath("com.betterjavacode.benefits.soap");
return marshaller;
}

@Bean
public UserClient userClient(Jaxb2Marshaller marshaller) {
// WSDL URL - http://localhost:8080/benefits/endpoints/users.wsdl
UserClient uc = new UserClient();
uc.setDefaultUri("http://localhost:8080/benefits/endpoints/users.wsdl");
uc.setMarshaller(marshaller);
uc.setUnmarshaller(marshaller);
return uc;
}
}

 

8.3 Run the SOAP web service client

We will define a class with main method to pass an argument of user id. Our client will call the web service with passed argument to return us the data if that user id existed in the database.


public class UserSoapClient {

    public static void main(String[] args) {
        AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
        ctx.register(ClientAppConfig.class);
        ctx.refresh();
        UserClient usc = ctx.getBean(UserClient.class);
        System.out.println(" For Employee: ");
        GetUserResponse response = usc.getUserById(1);
        System.out.println("Name: " + response.getUser()
            .getFirstname() + " "
            + response.getUser()
                .getLastname());
        System.out.println(" Job: " + response.getUser()
            .getJobtitle());

    }

}

 

9. Conclusion

In this article, we showed how to create a SOAP web service and how to build a client to consume the same SOAP web service using Spring Boot. The code for this is available at github

10. References

  1. Spring Web services tutorial
  2. SOAP Web service producer and consumer
  3. Consuming a web service in java and SOAP UI

Consuming a RESTful Webservice – Part IV

Continuing the series of posts on Spring Boot, in this post, we will investigate how to consume a REST API service we built previously. This will be a short post, but we will show how to read the data and how to post the data with some of the features Spring Boot offers to consume a REST service for client side. Eventual goal is to use this feature to call our rest service during runtime to use the data from database to display on views which a user will be able to see.

You can read previous posts on this series Part I, Part II and Part III .

Purpose

Purpose of this post is to read company data from Company REST API and also to create a company by posting company data using the same REST API.

Build a client

To consume a rest service programmatically, Spring provides a feature called RestTemplate. RestTemplate is easiest way for client to interact with server side code with just one line of code.

In our client code, we will need a RestTemplate object, REST service URL. Since this is a sample we are building, we will be adding a main method in this class to run this client side of the code. In real life scenarios, during runtime, a client code will call rest template to get server side data, use that data to massage or display to user on user interface.


RestTemplate restTemplate = new RestTemplate();
String resourceAPI_URL = "http://localhost:8080/benefits/v1/companies/{id}";
Company company = restTemplate.getForObject(resourceAPI_URL, Company.class, 1);

This code is showing that we are calling REST service to read company data for company with id that a client will pass.

Similarly, we will have another request to post the data on server side to create a company. The code for that will look like below:


String resourceAPI_POSTURL = "http://localhost:8080/benefits/v1/companies/";
Company comp = new Company();
comp.setName("XYZ Company");
comp.setStatusid(1);
comp.setType("Corporation");
comp.setEin("9343423232");
// comp.setCp(cp);
Company newcomp = restTemplate.postForObject(resourceAPI_POSTURL, comp, Company.class);

In this post, we showed how to use RestTemplate a feature that spring boot provides to consume a REST service. The code for this is available here

Notes from the book – Getting Real

Here, I will post the notes from the book Getting Real by 37Signals. You can download the copy on their website Getting Real.

Entire book can be summarized in the fact that you build a simple software and then add features. Do not complicate initial design and release. Get it done and ship it.

  • When there’s too many people involved, nothing gets done. The leaner you are, the faster – and better – things get done.
  • Getting real is a low-risk, low investment way to test new concepts.
  • Build less
    • Do less than your competitors to beat them. Solve the simple problems and leave hairy, difficult, nasty problems to everyone else. Instead of one-upping, try one-downing. Instead of outdoing, try underdoing.
    • When you solve your own problem, you create a tool that you’re passionate about. And passion is key. Passion means you’ll truly use it and care about it. And that’s the best way to get others to feel passionate about it too.
    • Outside money is plan B. Fund your own innovation and your ideas. Constraints drive innovation. If you’re creating software just to make a quick buck, it will show. Truth is a quick payout is pretty unlikely. So focus on building a quality tool that you and your customers can live with for a long time.
    • Launching something great that’s a little smaller in scope than planned is better than launching something mediocre and full of holes because you had to hit some magical time, budget and scope window.
    • Setting expectation is key.
    • The ability to change is key. Having everything fixed makes it touch to change. Injecting scope flexibility will introduce options based on your real experience building the product. Flexibility is your friend. Scope down. It’s better to make half a product than a half-assed product.
  • One bonus you get from having an enemy is a very clear marketing message. People are stroked by conflict. And they also understand a product by comparing it to others. With a chosen enemy, you’re feeding people a story they want to hear.
  • Your passion – or lack of – will shine through. The less your app is a chore to build, the better it will be. Keep it small and managable so you can actually enjoy the process.
  • When it comes to web technology, change must be easy and cheap. If you can’t change on the fly, you’ll lose ground to someone who can.
  • For first version of your app, start with only three people. That’s the magic number that will give you enough manpower yet allow you to stay streamlined and agile. Start with a developer, a designer and a sweeper.
  • Embrace the constraints, let them guide you. Constraints drive innovation and force focus. Instead of trying to remove them, use them to your advantage.
  • Details reveal themselves as you use what you’re building. You’ll see what needs more attention. You’ll feel what’s missing.
  • Don’t sweat stuff until you actually must. Don’t overbuild. Increase hardware and system software as necessary. If you’re slow for a week or two it’s not the end of the world. Just be honest to your customers, explain them you are experiencing some growing pains.
  • The customer is not always right. The truth is you have to sort out who’s right and who’s wrong for your app. The good news is that the internet makes finding the right people easier than ever.
  • In the beginning, make building a solid core product your priority instead of obsessing over scalability and server farms. Create a great app and then worry about what to do once it’s wildly successful.
  • The best software has a vision. The best software takes sides. When someone uses software, they’re not just looking for features, they are looking for an approach. Decide what your vision is and run with it.
  • What you really want to do is to build half a product that kicks ass.
  • The secret to building half a product instead of a half-ass product is saying no. Each time you are saying yes to a feature, you are adopting a child. The initial response is “not now”. If a request for a feature keeps coming back, that’s when we know it’s time to take a deeper look.
  • Build products and offer services you can manage. It’s easy to make promises. It’s much harder to keep them.
  • Don’t force conventions on people. Instead make your software general so everyone can find their own solution.
  • Just because x number of people request something, doesn’t mean you have to include it. Sometimes it’s better to just say no and maintain your vision for the product.
  • More isn’t the answer. Sometimes the biggest favor you can do for customers is to leave something out.
  • Running software is the best way to build momentum, rally your team, and flush out ideas that don’t work. It should be your number one priority from day one. Real things lead to real reactions. And that’s how you get to the truth.
  • Don’t expect to get it right for first time. Let the app grow and speak to you. Let it morph and evolve. With web-based software there’s no need to ship perfection. Design screens, use them, analyze them, and then start over again.
  • From Idea to implementation
    • Big questions – What does the app need to do? How will we know when it’s useful?  What exactly are we going to make? This is about high level ideas, not pixel-level details.
    • Get your ideas out of your head onto the paper. Sketches are quick, dirty and cheap.
    • Make an HTML version of that feature. Get something real posted, so everyone can see what it looks like on screen.
  • Preferences are evil because they create more software. More options require more code.
  • Decisions are temporary so make the call and move on. Done means you’re building momentum.
  • There’s no substitute for real people using your app in real ways. Get real data. Get real feedback. Then improve based on that info.
  • During alone time, give up IM, phone calls, meetings and emails. This is the time you can get in the zone for real work.
  • Simple rules for a meeting
    • Set a 30 minutes timer. Meeting should get over in 30 minutes. Period.
    • Invite as few people as possible.
    • Never have a meeting without a clear agenda.
  • Quick wins that you can celebrate, are great motivators. Release something today.
  • Too many apps start with a program-first mentality. That’s a bad idea. Programming is the heaviest component of building an app, meaning it’s the most expensive and hardest to change. Instead, start by designing first.
  • For each screen, you need to consider three possible states:
    • Regular
    • Blank
    • Error
  • You need to speak same language as your audience too. Just because you’re writing a web app doesn’t mean you can get away with technical jargon. Good writing is good design.
  • The fewer screens you have to worry about, the better they’ll turn out.
  • Solving 80% of the original problem for 20% of the effort is a major win.
  • Don’t be afraid to say no to feature requests that are hard to do.
  • Your code can guide you to fixes that are cheap and light.
  • Functional specs are useless. You know the least about something when you begin to build it. The more you build it, the more you use it, the more you know it.
  • Write one page story about what the app needs to do. Use plain language and make it quick. If it takes more than one page to explain it, then it’s too complex.
  • Build, don’t write. If you need to explain something, try mocking up and prototyping it rather than writing a long-winded document.  An actual interface or prototype is on its way to becoming a real product.
  • To build a better interface, do as your customers do and you’ll understand them better.
  • Your product has a voice and it is talking to your customer 24 hours a day.
  • Make signup and cancellation a painless process. Make sure people can get their data out if they decide to leave.
  • Hollywood Launch
    • Teaser
    • Preview
    • Launch
  • Start off by creating a blog that not only touts your product but offers helpful advice, tips, tricks, links etc.
  • Get advance buzz and signups going asap.
  • Promote through education
    • When the subject you are teaching is your app, it serves dual purpose. You can give something back to the community that supports you and score some nice promotional exposure at the same time.
    • Update your blog regularly and post tips & tricks, articles that help your customer and community
  • If the comments you are receiving for your app, are negative, pay attention. Show you’re listening. Respond to critiques thoughtfully.
  • Listening to customers is the best way to get in tune with your product’s strengths and weaknesses.
  • Strive to build a tool that requires zero training. The less complex is your app, the less you’ll need to help people out.
  • Be as open, honest and transparent as possible. Don’t keep secrets or hide behind spin. An informed customer is your best customer.
  • Go with the flow – be open to new paths and changes in direction. Part of the beauty of web app is its fluidity.

Error Handling and Logging in Spring Boot REST API – Part III

In previous posts, I wrote about how to create a spring boot REST API Part I and how to add swagger documentation for REST API Part II. In this post, we will add error handling and logging to our REST API. Error handling and Logging are two different ideas, so I will divide this post in two sections.

1. Logging

In most production applications, logging is critical and it is used for multiple purposes. Few of those uses are debugging the production issues or auditing for the application. Over the years, different logging libraries have evolved to use in java based applications. slf4j is the most popular framework as it provides a simple abstraction layer to any kind of logging framework.

In our tutorial for this application, we will be using log4j2 which is the most recent and advance logging library out there. It provides lot of useful features for performance, support for multiple APIs, advance filtering, automatic reloading of configurations etc. We will not cover any of these in this article, if you are interested to read about log4j2 libraries, read here.

Add log4j2 library in application –

To use log4j2, we will add the maven dependency to our project’s pom file. This should look like below

 <dependency>
 <groupId>org.apache.logging.log4j</groupId>
 <artifactId>log4j-api</artifactId>
 </dependency>
 <dependency>
 <groupId>org.apache.logging.log4j</groupId>
 <artifactId>log4j-core</artifactId>
 </dependency>

Add log4j2 configuration file

To enable logging, we will have to add a configuration file in our application. This configuration file can be XML, JSON or YAML file. We will be using a XML file log4j2.xml which will look like below

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="INFO">
 <Appenders>
 <Console name="Console" target="SYSTEM_OUT">
 <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n" />
 </Console>
 <File name="BenefitsFile" fileName="benefits.log" append="true">
 <PatternLayout pattern="%d{yyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
 </File>
 </Appenders>
 <Loggers>
 <Root level="debug">
 <AppenderRef ref="Console" />
 <AppenderRef ref="BenefitsFile"/>
 </Root>
 </Loggers>
</Configuration>

So we are using <code> Console </code> and <code> BenefitsFile </code> as two loggers which will log into a console and file respectively. We are setting log level to DEBUG. If you log any messages with a level lower than DEBUG, they will be logged into console or file. We will have to add a file benefits.log in classpath to achieve this logging in file. Log pattern is with date time, log level, class from which log is originating and log message.

Add logging in application code

Once we have required logging libraries and logging configuration adjusted, we can add logging in our code to capture this logging during runtime execution. In one of the managers CompanyManagerImpl, we will add a logger.

public static final Logger LOGGER = LogManager.getLogger(CompanyManagerImpl.class);

@Override
public List<Company> getAllCompanies()
{
LOGGER.info(" Enter >> getAllCompanies() ");
List<Company> cList = (List<Company>) companyRepository.findAll();
LOGGER.info(" Exit << getAllCompanies() ");
return cList;
}

Now once we execute our spring boot application, we can capture the logs in console or file. The file will be benefits.log.

2. Error Handling

We will not write about exceptions in detail as it has been covered in this post Exceptions. We will create our own custom exception which will be extended from WebApplicationException which jersey library provides.

This will look like below:


package com.betterjavacode.benefits.utilities;

import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.Response;

public class InvalidRequestException extends WebApplicationException {

/**
*
*/
private static final long serialVersionUID = 1L;
private int errorcode = 00; // 00 indicates - no error

public InvalidRequestException() {

}

public InvalidRequestException(int errorcode, String message) {
super(Response.status(Response.Status.BAD_REQUEST)
.entity(message)
.build());
this.errorcode = errorcode;
}

public InvalidRequestException(int errorcode, String message, Throwable cause) {
super(cause, Response.status(Response.Status.BAD_REQUEST)
.entity(message)
.build());
this.errorcode = errorcode;
}
}

Now we can use this custom exception in our managers when we want to throw an error message to indicate if there is anything wrong with client request. Similarly we can build another exception to show if there is anything wrong on server side. Following snippet shows from CompanyManagerImpl where we have shown how to throw this exception.


@Override
public Company getCompany(int guid) {
LOGGER.info(" Enter >> getCompany() ");
Company company = companyRepository.findOne(guid);
if (company == null) {
LOGGER.info(" Exit << createCompany() ");
throw new InvalidRequestException(400, "Company not found");
}
LOGGER.info(" Exit << getCompany() ");
return company;
}

In this post, we showed how to handle logging and errors in a REST API. The code for this is available on github repository.

 

Swagger Documentation for Spring Boot rest API – Part II

In this post, we will show how to add swagger documentation to Spring boot rest API. We learned how to create a Spring Boot REST API. In Microservices’ world, these days documenting your API is a standard norm. Swagger provides a handy interface and a simple way to build these documentations that any client can test any moment. They don’t need to have all the services on their environment.

What is Swagger?

Swagger was intended to provide a standard, language-agnostic interface to REST APIs which allow anyone to understand the capabilities of a service without any source code, documentation of source code. You can find more details about Swagger here.

How to add swagger documentation?

In our previous post, we added Spring boot REST API. We will add swagger documentation to the same REST API.

  1. Add Maven dependencies

To start with, let’s add maven dependencies for swagger jars.

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>

2. Add Swagger bean in configuration

In our main starting Application class, we will add few configurations for setting up a bean which will handle swagger documentation. In below code, I show what I have added in Application.java file. Basically, we have created a new bean of type Docket which takes care of swagger configuration.

@EnableSwagger2
@SpringBootApplication(scanBasePackages = { "com.betterjavacode.benefits" })
public class Application {

public static void main(String[] args) {
 SpringApplication.run(Application.class, args);

}

@Bean
 public Docket benefitsApi() {
 return new Docket(DocumentationType.SWAGGER_2).groupName("Benefits")
 .apiInfo(apiInfo())
 .select()
 .apis(RequestHandlerSelectors.any())
 .paths(PathSelectors.any())
 .build()
 .pathMapping("/");

}

private ApiInfo apiInfo() {
 return new ApiInfoBuilder().title("Benefits REST Service")
 .description(" A simple REST service for Benefits software ")
 .contact(new Contact("Yogesh Mali", "https://betterjavacode.com", ""))
 .version("1.0")
 .build();
 }
}

3. Show Swagger documentation

Now once we have added the configuration, we can build our project with maven clean install. After successful build, run the project from eclipse as a Java application. We will access swagger documentation from URL http://localhost:8080/swagger-ui.html . This will look like below :

Swagger

Source code for this post is available at Spring-boot-rest-api-with-swagger.

How To – Spring Boot CRUD Rest API – Part I

As part of this post, we will learn how to write a CRUD Rest API using Spring Boot. Spring boot provides some cool features to create a production ready Spring application that can be deployed as a war file on any environment. This will be a series of posts, but we will start with creation of a simple REST API.

What you’ll need 

  1. Eclipse Mars.2 Release
  2. Java version 1.8
  3. MySQL 5.0 or higher
  4. Maven 3.0 or higher

What we’ll cover 

In this article, we will cover following items

  1. Create a Maven project
  2. Assemble pom file for all dependencies
  3. Create entity classes
  4. Create business logic to handle data
  5. Create a rest controller
  6. Run the API in tomcat

Create a Maven project

As first step, let’s create a maven project in eclipse. You can create this by going into File > New > Maven Project.

Select Archtype as maven-archtype-webapp.

Enter artifactid as benefits and groupid as com.betterjavacode

Assemble pom file for all dependencies

We will be using spring-boot and all the required dependencies including spring-data. Spring data JPA provides lot of useful enhancements that can be seamlessly used with spring-boot project. Spring-data will cover the data access layer which is basically implements persistence. Once we use spring-data, we don’t have to add any external hibernate or eclipselink JPA APIs. Also some of the data access repositories provided by spring-data makes implementing data access layer code less worrisome.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.betterjavacode</groupId>
 <artifactId>Benefits</artifactId>
 <packaging>war</packaging>
 <version>0.0.1-SNAPSHOT</version>
 <name>Benefits Maven Webapp</name>
 <url>http://maven.apache.org</url>
 <parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>1.4.2.RELEASE</version>
 </parent>
 <dependencies>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
 </dependency>

 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-data-jpa</artifactId>
 </dependency>
 <dependency>
 <groupId>mysql</groupId>
 <artifactId>mysql-connector-java</artifactId>
 <scope>runtime</scope>
 </dependency>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-jdbc</artifactId>
 </dependency>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-test</artifactId>
 </dependency>
 <dependency>
 <groupId>org.slf4j</groupId>
 <artifactId>slf4j-api</artifactId> 
 </dependency>
 <dependency>
 <groupId>org.apache.logging.log4j</groupId>
 <artifactId>log4j-api</artifactId>
 </dependency>
 <dependency>
 <groupId>org.apache.logging.log4j</groupId>
 <artifactId>log4j-core</artifactId>
 </dependency>
 <dependency>
 <groupId>junit</groupId>
 <artifactId>junit</artifactId>
 <scope>test</scope>
 </dependency>
 </dependencies>
 <build>
 <plugins>
 <plugin>
 <artifactId>maven-compiler-plugin</artifactId>
 <version>3.3</version>
 <configuration>
 <source>1.8</source>
 <target>1.8</target>
 </configuration>
 </plugin>
 <plugin>
 <artifactId>maven-war-plugin</artifactId>
 <version>2.6</version>
 <configuration>
 <warSourceDirectory>WebContent</warSourceDirectory>
 <failOnMissingWebXml>false</failOnMissingWebXml>
 </configuration>
 </plugin>
 </plugins>
 <finalName>Benefits</finalName>
 </build>
</project>

Create entity classes

We will be creating a rest api for Benefits service which will have companies and users as main objects. We are only covering basic data model classes at the moment, but as part of the series we will develop a web application. Each company will company profile and each user will userprofile. So we will have four basic entities Company, CompanyProfile, User, UserProfile.

package com.betterjavacode.benefits.entities;

import java.io.Serializable;

import javax.persistence.CascadeType;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.FetchType;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.JoinColumn;
import javax.persistence.OneToOne;
import javax.persistence.Table;

@Entity(name = "Company")
@Table(name = "company")
public class Company implements Serializable {

/**
*
*/
private static final long serialVersionUID = 1L;

public Company() {

}

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private int id;

@Column
private String name;

@Column
private int statusid;

@OneToOne(cascade = CascadeType.PERSIST, fetch = FetchType.EAGER)
@JoinColumn(name = "companyprofileid")
private CompanyProfile cp;

@Column
private String type;

@Column
private String ein;

public int getId() {
return id;
}

public void setId(int id) {
this.id = id;
}

public String getName() {
return name;
}

public void setName(String name) {
this.name = name;
}

public int getStatusid() {
return statusid;
}

public void setStatusid(int statusid) {
this.statusid = statusid;
}

public CompanyProfile getCp() {
return cp;
}

public void setCp(CompanyProfile cp) {
this.cp = cp;
}

public String getType() {
return type;
}

public void setType(String type) {
this.type = type;
}

public String getEin() {
return ein;
}

public void setEin(String ein) {
this.ein = ein;
}

}

package com.betterjavacode.benefits.entities;

import java.io.Serializable;
import java.util.Date;

import javax.persistence.CascadeType;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.FetchType;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.JoinColumn;
import javax.persistence.OneToOne;
import javax.persistence.Table;

@Entity(name = "User")
@Table(name = "user")
public class User implements Serializable {

/**
*
*/
private static final long serialVersionUID = 1L;

public User() {

}

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private int id;

@Column
private Date createdate;

@Column
private String email;

@Column
private String firstname;

@Column
private String middlename;

@Column
private String lastname;

@Column
private String username;

@Column
private String jobtitle;

@OneToOne(cascade = CascadeType.PERSIST, fetch = FetchType.EAGER)
@JoinColumn(name = "userprofileid")
private UserProfile userprofile;

public int getId() {
return id;
}

public void setId(int id) {
this.id = id;
}

public Date getCreatedate() {
return createdate;
}

public void setCreatedate(Date createdate) {
this.createdate = createdate;
}

public String getEmail() {
return email;
}

public void setEmail(String email) {
this.email = email;
}

public String getFirstname() {
return firstname;
}

public void setFirstname(String firstname) {
this.firstname = firstname;
}

public String getMiddlename() {
return middlename;
}

public void setMiddlename(String middlename) {
this.middlename = middlename;
}

public String getLastname() {
return lastname;
}

public void setLastname(String lastname) {
this.lastname = lastname;
}

public String getUsername() {
return username;
}

public void setUsername(String username) {
this.username = username;
}

public String getJobtitle() {
return jobtitle;
}

public void setJobtitle(String jobtitle) {
this.jobtitle = jobtitle;
}

public UserProfile getUserprofile() {
return userprofile;
}

public void setUp(UserProfile up) {
this.userprofile = up;
}

}

Create business logic to handle the data

Part of our architecture for REST API, we will have following three layers

  1. Rest layer
  2. Business object layer
  3. Data access layer

So in Business object layer, we will implement all the managers which will handle processing of rest requests to create, update, read or delete the data. In subsequent posts, we will enhance this layer to handle logging, error handling and more.

package com.betterjavacode.benefits.managers;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;

import com.betterjavacode.benefits.entities.User;
import com.betterjavacode.benefits.interfaces.UserManager;
import com.betterjavacode.benefits.repositories.UserRepository;

public class UserManagerImpl implements UserManager {

private UserRepository userRepository;

@Autowired
public void setUserRepository(UserRepository userRepository) {
this.userRepository = userRepository;
}

@Override
public User createUser(User u) {
if (u != null) {
User user = userRepository.save(u);
return user;
} else {
return null;
}
}

@Override
public User updateUser(User u) {
// TODO Auto-generated method stub
return null;
}

@Override
public User getUser(int id) {
User user = userRepository.findOne(id);
if (user == null) {
return null;
}
return user;
}

@Override
public List getAllUsers() {
List userList = (List) userRepository.findAll();
return userList;
}

@Override
public void deleteUser(int guid) {
// TODO Auto-generated method stub
User user = userRepository.findOne(guid);
if (user == null) {
return;
}
userRepository.delete(user);
}

}

Create a REST controller

One of the best uses of Spring boot is to create rest API and the feature it offers for the same is to use REST controller. Spring-boot offers an annotation for the same as @RestController.

package com.betterjavacode.benefits.controller;

import java.util.List;

import javax.ws.rs.core.Response;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.betterjavacode.benefits.entities.User;
import com.betterjavacode.benefits.interfaces.UserManager;

@RestController
@RequestMapping("benefits/v1")
public class UserService {

@Autowired
UserManager userMgr;

@RequestMapping(value = "/users/", method = RequestMethod.POST)
public User createUser(User user) {
User u = userMgr.createUser(user);
return u;
}

@RequestMapping(value = "/users/{id}", method = RequestMethod.GET)
public User getUser(@PathVariable("id") int id) {
User u = userMgr.getUser(id);
return u;
}

@RequestMapping(value = "/users/", method = RequestMethod.GET)
public List getAllUsers() {
List cList = userMgr.getAllUsers();
return cList;
}

@RequestMapping(value = "/users/", method = RequestMethod.PUT)
public User updateUser(User user) {
User u = userMgr.updateUser(user);
return u;
}

@RequestMapping(value = "/users/{id}", method = RequestMethod.DELETE)
public Response deleteUser(@PathVariable("id") int id) {
userMgr.deleteUser(id);
return Response.status(Response.Status.OK)
.build();
}
}

package com.betterjavacode.benefits.controller;

import java.util.List;

import javax.ws.rs.core.Response;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.betterjavacode.benefits.entities.Company;
import com.betterjavacode.benefits.interfaces.CompanyManager;

@RestController
@RequestMapping("benefits/v1")
public class CompanyService {

@Autowired
CompanyManager compMgr;

@RequestMapping(value = "/companies/", method = RequestMethod.POST)
public Company createCompany(Company company) {
Company c = compMgr.createCompany(company);
return c;
}

@RequestMapping(value = "/companies/{id}", method = RequestMethod.GET)
public Company getCompany(@PathVariable("id") int id) {
Company c = compMgr.getCompany(id);
return c;
}

@RequestMapping(value = "/companies/", method = RequestMethod.GET)
public List getAllCompanies() {
List cList = compMgr.getAllCompanies();
return cList;
}

@RequestMapping(value = "/companies/", method = RequestMethod.PUT)
public Company updateCompany(Company company) {
Company c = compMgr.updateCompany(company);
return c;
}

@RequestMapping(value = "/companies/{id}", method = RequestMethod.DELETE)
public Response deleteCompany(@PathVariable("id") int id) {
compMgr.deleteCompany(id);
return Response.status(Response.Status.OK)
.build();
}
}

Run the API in tomcat

We are using embedded tomcat in this Spring-boot project. So once we are done building and installing the code through maven, we can run the project through eclipse or standalone war file in tomcat. For our demo purposes, we will run this application through eclipse, which will start embedded tomcat.

If we execute the url http://localhost:8080/benefits/v1/users/1 – it will display json for user data as below

result

You can find the source code for this project Github Repository.