Working With Response Parsers

Parsers are used to extract the body of an HTTP response and make the data available in a usable format. Several commonly utilized response parsers are prefabricated in the library and can be used with the @Parser annotation.

This annotation can be applied to an endpoint or to a request method. When applied to an endpoint, the parser is shared among all requests. If a specific request method requires an alternate parser, the annotation can be reapplied to the target request with the required parser definition.

####1. Parsing String Responses

• This essentially returns the raw unprocessed content which is received in the response body.

@Endpoint("www.google.com")
@Parser(PARSER_TYPE.STRING)
public interface CurrencyConverterEndpoint {}

####2. Parsing JSON Responses

• JSON responses can be automatically parsed to obtain an instance of the entity.

• The previous currency converter example, which responds with JSON having the format {lhs:"", rhs:"", error: "", icc:true}, is revisited in this topic.

An instance of the corresponding entity can be received by specifying it as the service return type and together with a JSON parser definition.

######Entity

public class Conversion implements Serializable {

      private String lhs;
      private String rhs;
      private String error;
      private boolean icc;

      
      /* serialVersionUID, Accessors, Mutators, 
       * hashCode(), equals() and toString() omitted */
      
}

######Definition

@Parser(PARSER_TYPE.JSON)
@Request(path = "/ig/calculator")
public abstract Conversion convert(@Param("q") String conversionString);

######Invocation

Conversion conversion = ccEndpoint.convert("1USD=?AUD");
logger.info(conversion.getLhs() + " = " + conversion.getRhs());

######Output

$ 1 U.S. dollar = 0.949487277 Australian dollars

####3. Creating Custom Response Parsers

• Custom parsers are created by extending AbstractResponseParser and specifying the parser return type as the generic. Its involves the implementation of 2 methods.

1. The processResponse() method receives the HttpResponse which should be used to extract the response content and perform the parsing.

2. The ```getType()``` method should return the ```Class``` of the parser return type.

######Entity

public class Lyric implements Serializable {

      private List lines;

      public Lyric(String lyric) {
          
          this.lines = Arrays.asList(lyric.split(","));
      }

      
      /* serialVersionUID, Accessors, Mutators, 
       * hashCode(), equals() and toString() omitted */
      
}

######Extension

public class LyricResponseParser extends AbstractResponseParser<Lyric> {

      @Override
      public Lyric processResponse(HttpResponse httpResponse) throws Exception {

          String responseString = EntityUtils.toString(httpResponse.getEntity());

          return new Lyric(responseString);
      }

      @Override
      public Class<Lyric> getType() {

          return Lyric.class;
      }
}

######Definition

@Request
@Parser(type = LyricResponseParser.class)
public abstract Lyric getLyric(@Param("artist") String artist, 
                               @Param("song") String song);

######Invocation

Lyric hades = endpoint.getLyric("Kalmah", "Hades");