src/third_party/cacheinvalidation/src/java/com/google/ipc/invalidation/external/client/android/service/Response.java

   1 /*
   2  * Copyright 2011 Google Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package com.google.ipc.invalidation.external.client.android.service;
  18
  19 import android.os.Bundle;
  20
  21 /**
  22  * Creates and interprets response message bundles returned by the invalidation
  23  * service or application clients in response to request or event messages.
  24  *
  25  */
  26 public final class Response extends Message {
  27   private static final AndroidLogger logger = AndroidLogger.forTag("Response");
  28
  29   /** Contains the list of parameter names that are valid for response bundles. */
  30   public static class Parameter extends Message.Parameter {
  31     private Parameter() {} // not instantiable
  32
  33     /**
  34      * An integer status code indicating success or failure.
  35      *
  36      * @see Status
  37      */
  38     public static final String STATUS = "status";
  39   }
  40
  41   /** Defined values for the {@link Parameter#STATUS} parameter. */
  42   public static class Status {
  43     public static final int SUCCESS = 0;
  44     public static final int INVALID_CLIENT = 1;
  45     public static final int RUNTIME_ERROR = -1;
  46     public static final int UNKNOWN = -2;
  47   }
  48
  49   /**
  50    * A builder class for constructing new response messages.
  51    *
  52    * @see #newBuilder
  53    */
  54   public static class Builder extends Message.Builder<Response, Builder> {
  55
  56     // Instantiate using newBuilder()
  57     private Builder(int actionOrdinal, Bundle b) {
  58       super(actionOrdinal, b);
  59     }
  60
  61     /**
  62      * Stores a status value within a response message.
  63      */
  64     public Builder setStatus(int status) {
  65       bundle.putInt(Parameter.STATUS, status);
  66       return this;
  67     }
  68
  69     /**
  70      * Sets the status to {@link Status#RUNTIME_ERROR} and the error message to
  71      * the exception message within a response message.
  72      */
  73     public void setException(Exception exception) {
  74       if (exception instanceof AndroidClientException) {
  75         AndroidClientException ace = (AndroidClientException) exception;
  76         setStatus(ace.status);
  77         setError(ace.message);
  78       } else {
  79         setStatus(Status.RUNTIME_ERROR);
  80         setError(exception.getMessage());
  81       }
  82     }
  83
  84     /**
  85      * Returns an response containing the set parameters.
  86      */
  87     @Override
  88     public Response build() {
  89       return new Response(bundle);
  90     }
  91   }
  92
  93   /**
  94    * Constructs a new builder for a response associated with the provided action
  95    * that will store parameters into the provided bundle.
  96    */
  97   public static Builder newBuilder(int actionOrdinal, Bundle b) {
  98     return new Builder(actionOrdinal, b);
  99   }
 100
 101   /**
 102    * Constructs a new response using the contents of the provided parameter bundle.
 103    */
 104   public Response(Bundle bundle) {
 105     super(bundle);
 106   }
 107
 108   /**
 109    * Returns the status from a response message or {@link Status#UNKNOWN} if not
 110    * set by the callee (presumed failure).
 111    */
 112   public int getStatus() {
 113     return parameters.getInt(Parameter.STATUS, Status.UNKNOWN);
 114   }
 115
 116   /**
 117    * Logs an error if the response message contains a status value other than
 118    * {@link Status#SUCCESS}.
 119    */
 120   public void warnOnFailure() {
 121     int status = getStatus();
 122     if (status != Status.SUCCESS) {
 123       String error = parameters.getString(Parameter.ERROR);
 124       if (error == null) {
 125         error = "Unexpected status value:" + status;
 126       }
 127       logger.warning("Error from AndroidInvalidationService: %s", error);
 128     }
 129   }
 130 }