java/src/main/com/google/appengine/api/log/LogQuery.java

   1 // Copyright 2011 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.log;
   4
   5 import com.google.appengine.api.log.LogService.LogLevel;
   6 import com.google.common.base.Pair;
   7 import com.google.common.collect.ImmutableList;
   8
   9 import java.io.Serializable;
  10 import java.util.ArrayList;
  11 import java.util.Comparator;
  12 import java.util.HashSet;
  13 import java.util.List;
  14 import java.util.Set;
  15 import java.util.regex.Matcher;
  16 import java.util.regex.Pattern;
  17
  18 /**
  19  * Allows users to customize the behavior of {@link LogService#fetch(LogQuery)}.
  20  * <p>
  21  * {@code startTime} is the earliest request completion or last-update time
  22  * that results should be fetched for, in seconds since the Unix epoch. If
  23  * {@code null} then no requests will be excluded for ending too long ago.
  24  * <p>
  25  * {@code endTime} is the latest request completion or last-update time that
  26  * results should be fetched for, in seconds since the Unix epoch. If
  27  * {@code null} then no requests will be excluded for ending too recently.
  28  * <p>
  29  * {@code offset} is a cursor into the log stream retrieved from a previously
  30  * emitted {@link RequestLogs#getOffset}. This iterator will begin returning
  31  * logs immediately after the record from which the offset came. If
  32  * {@code null}, the query will begin at {@code startTime}.
  33  * <p>
  34  * {@code minLogLevel} is a {@link LogService.LogLevel} which serves as a
  35  * filter on the requests returned. Requests with no application logs at or
  36  * above the specified level will be omitted. Works even if
  37  * {@code includeAppLogs} is not True.
  38  * <p>
  39  * {@code includeIncomplete} selects whether requests that have started but not
  40  * yet finished should be included in the query. Defaults to False.
  41  * <p>
  42  * {@code includeAppLogs} specifies whether or not to include application logs
  43  * in the query results. Defaults to False.
  44  * <p>
  45  * {@code majorVersionIds} specifies versions of the application's default
  46  * module for which logs records should retrieved.
  47  * <p>
  48  * {@code versions} specifies module versions of the application for which
  49  * logs should be retrieved.
  50  * <p>
  51  * {@code requestIds}, if not {@code empty()}, indicates that instead of a
  52  * time-based scan, logs for the specified requests should be returned.
  53  * See the Request IDs section of <a
  54  * href="https://developers.google.com/appengine/docs/java/runtime#The_Environment}">
  55  * the Java Servlet Environment documentation</a> for how to retrieve these IDs
  56  * at runtime. Malformed request IDs cause an exception and unrecognized request IDs
  57  * are ignored. This option may not be combined with other filtering options such as
  58  * startTime, endTime, offset, or minLogLevel. When {@code requestIds} is not {@code empty()},
  59  * {@code majorVersionIds} are ignored. Logs are returned in the order requested.
  60  * <p>
  61  * {@code batchSize} specifies the internal batching strategy of the returned
  62  * {@link java.lang.Iterable Iterable&lt;RequestLogs&gt;}. Has no impact on the
  63  * result of the query.
  64  * <p>
  65  * Notes on usage:<br>
  66  * The recommended way to instantiate a {@code LogQuery} object is to
  67  * statically import {@link Builder}.* and invoke a static
  68  * creation method followed by an instance mutator (if needed):
  69  *
  70  * <pre>
  71  * import static com.google.appengine.api.log.LogQuery.Builder.*;
  72  *
  73  * ...
  74  *
  75  * // All requests, including application logs.
  76  * iter = logService.fetch(withIncludeAppLogs(true));
  77  *
  78  * // All requests ending in the past day (or still running) with an info log or higher.
  79  * Calendar cal = Calendar.getInstance();
  80  * cal.add(Calendar.DAY_OF_MONTH, -1);
  81  * iter = logService.fetch(withEndTimeMillis(cal.time())
  82  *     .includeIncomplete(true).minimumLogLevel(LogService.INFO));
  83  * </pre>
  84  *
  85  * There are a couple of ways to configure {@link LogQuery} to limit
  86  * {@link LogService#fetch(LogQuery)} to only return log records for specific
  87  * module versions.
  88  * <ol>
  89  * <li><b>{@link #versions(List)}({@link Builder#withVersions(List)})</b> -
  90  * Includes designated module versions for the application.
  91  * <li><b>{@link #majorVersionIds(List)} ({@link Builder#withMajorVersionIds(List)})</b> -
  92  *  Includes designated versions of the default module for the application.
  93  * </ol>
  94  * For a particular {@link LogQuery} only one of these methods may be used. If neither is used,
  95  * {@link LogService#fetch(LogQuery)} results may include any module version.
  96  *
  97  * It is not allowed to call both {@link #versions(List)} ({@link Builder#withVersions(List)})
  98  * and {@link #requestIds(List)}({@link Builder#withRequestIds(List)} for the same {@link LogQuery}.
  99  *
 100  * Please avoid using any of these deprecated methods as they will be removed from this
 101  * API in an upcoming release.
 102  * <ol>
 103  * <li><b>{@link Builder#withServerVersions(List)}</b>
 104  * <li><b>{@link Builder#withModuleVersions(List)}</b>
 105  * <li><b>{@link #getServerVersions()}</b>
 106  * <li><b>{@link #serverVersions(List)}</b>
 107  * <li><b>{@link #getModuleVersions()}</b>
 108  * <li><b>{@link #moduleVersions(List)}</b>
 109  * </ol>
 110  *
 111  */
 112 public final class LogQuery implements Cloneable, Serializable {
 113   private static final long serialVersionUID = 3660093076203855168L;
 114   static final Comparator<Version> VERSION_COMPARATOR = new VersionComparator();
 115
 116   private String offset;
 117
 118   private Long startTimeUsec;
 119
 120   private Long endTimeUsec;
 121
 122   private int batchSize = LogService.DEFAULT_ITEMS_PER_FETCH;
 123
 124   private LogLevel minLogLevel;
 125   private boolean includeIncomplete = false;
 126   private boolean includeAppLogs = false;
 127   private List<String> majorVersionIds = new ArrayList<String>();
 128   private List<Pair<String, String>> moduleVersions = new ArrayList<Pair<String, String>>();
 129   private final List<Version> versions = new ArrayList<Version>();
 130
 131   private List<String> requestIds = new ArrayList<String>();
 132
 133   private static final String MAJOR_VERSION_ID_REGEX = "[a-z\\d][a-z\\d\\-]{0,99}";
 134   private static final Pattern VERSION_PATTERN = Pattern.compile(MAJOR_VERSION_ID_REGEX);
 135   private static final String REQUEST_ID_REGEX = "\\A\\p{XDigit}+\\z";
 136   private static final Pattern REQUEST_ID_PATTERN = Pattern.compile(REQUEST_ID_REGEX);
 137
 138   /**
 139    * Specifies a version of a module.
 140    */
 141   public static final class Version implements Serializable {
 142     private static final long serialVersionUID = 3697597908142270764L;
 143     private static final String INVALID_MODULE_ID_MESSAGE_TEMPLATE = "Invalid module id '%s'";
 144     private static final String INVALID_VERSION_ID_MESSAGE_TEMPLATE = "Invalid version id '%s'";
 145     private final String moduleId;
 146     private final String versionId;
 147
 148     /**
 149      * Constructs a {@link Version}.
 150      * @param moduleId A valid module id.
 151      * @param versionId A valid version id.
 152      */
 153     public Version(String moduleId, String versionId) {
 154       this.moduleId = verifyId(moduleId, INVALID_MODULE_ID_MESSAGE_TEMPLATE);
 155       this.versionId = verifyId(versionId, INVALID_VERSION_ID_MESSAGE_TEMPLATE);
 156     }
 157
 158     /**
 159      * Returns the moduleId.
 160      */
 161     public String getModuleId() {
 162       return moduleId;
 163     }
 164
 165     /**
 166      * Returns the version id.
 167      */
 168     public String getVersionId() {
 169       return versionId;
 170     }
 171
 172     @Override
 173     public int hashCode() {
 174       final int prime = 31;
 175       int result = 1;
 176       result = prime * result + ((moduleId == null) ? 0 : moduleId.hashCode());
 177       result = prime * result + ((versionId == null) ? 0 : versionId.hashCode());
 178       return result;
 179     }
 180
 181     @Override
 182     public boolean equals(Object obj) {
 183       if (this == obj) {
 184         return true;
 185       }
 186       if (obj == null) {
 187         return false;
 188       }
 189       if (getClass() != obj.getClass()) {
 190         return false;
 191       }
 192       Version other = (Version) obj;
 193       if (moduleId == null) {
 194         if (other.moduleId != null) {
 195           return false;
 196         }
 197       } else if (!moduleId.equals(other.moduleId)) {
 198         return false;
 199     }
 200
 201     if (versionId == null) {
 202       if (other.versionId != null) {
 203         return false;
 204       }
 205     } else if (!versionId.equals(other.versionId)) {
 206       return false;
 207     }
 208     return true;
 209   }
 210
 211     @Override
 212     public String toString() {
 213       return "Version: moduleId=" + moduleId + " versionId=" + versionId;
 214     }
 215
 216     /**
 217      * Verifies and returns a module id or version id.
 218      *
 219      * Note this verification uses the VERSION_PATTERN regular expression which will catch
 220      * many but not all syntactic errors.
 221      *
 222      * @param moduleOrVersionId The module or version id to verify.
 223      * @param messageTemplate A message template with a placeholder for the invalid value.
 224      * @return moduleOrVersionId
 225      * @throws IllegalArgumentException if moduleOrVersionId is not valid.
 226      */
 227     private static String verifyId(String moduleOrVersionId, String messageTemplate) {
 228       Matcher matcher = VERSION_PATTERN.matcher(moduleOrVersionId);
 229       if (!matcher.matches()) {
 230         throw new IllegalArgumentException(String.format(messageTemplate, moduleOrVersionId));
 231       }
 232       return moduleOrVersionId;
 233     }
 234   }
 235
 236   /**
 237    * Compares {@link Version} values by {@link Version#getModuleId()} and
 238    * breaks ties by comparing by {@link Version#getVersionId()}
 239    */
 240   private static class VersionComparator implements Comparator<Version> {
 241     @Override
 242     public int compare(Version version1, Version version2) {
 243       int result = version1.getModuleId().compareTo(version2.getModuleId());
 244       if (result == 0) {
 245         result = version1.getVersionId().compareTo(version2.getVersionId());
 246       }
 247       return result;
 248     }
 249   }
 250
 251   /**
 252    * Contains static creation methods for {@link LogQuery}.
 253    */
 254   public static final class Builder {
 255     /**
 256      * Create a {@link LogQuery} with the given offset.
 257      * Shorthand for <code>LogQuery.Builder.withDefaults().offset(offset);</code>.
 258      * Please read the {@link LogQuery} class javadoc for an explanation of
 259      * how offsets are used.
 260      * @param offset the offset to use.
 261      * @return The newly created LogQuery instance.
 262      */
 263     public static LogQuery withOffset(String offset) {
 264       return withDefaults().offset(offset);
 265     }
 266
 267     /**
 268      * Create a {@link LogQuery} with the given start time.
 269      * Shorthand for <code>LogQuery.Builder.withDefaults().startTimeMillis(startTimeMillis);</code>.
 270      * Please read the {@link LogQuery} class javadoc for an explanation of
 271      * how start time is used.
 272      * @param startTimeMillis the start time to use, in milliseconds.
 273      * @return The newly created LogQuery instance.
 274      */
 275     public static LogQuery withStartTimeMillis(long startTimeMillis) {
 276       return withDefaults().startTimeMillis(startTimeMillis);
 277     }
 278
 279     /**
 280      * Create a {@link LogQuery} with the given start time.
 281      * Shorthand for <code>LogQuery.Builder.withDefaults().startTimeUsec(startTimeUsec);</code>.
 282      * Please read the {@link LogQuery} class javadoc for an explanation of
 283      * how start time is used.
 284      * @param startTimeUsec the start time to use, in microseconds.
 285      * @return The newly created LogQuery instance.
 286      */
 287     public static LogQuery withStartTimeUsec(long startTimeUsec) {
 288       return withDefaults().startTimeUsec(startTimeUsec);
 289     }
 290
 291     /**
 292      * Create a {@link LogQuery} with the given end time.
 293      * Shorthand for <code>LogQuery.Builder.withDefaults().endTimeMillis(startTimeMillis);</code>.
 294      * Please read the {@link LogQuery} class javadoc for an explanation of
 295      * how end time is used.
 296      * @param endTimeMillis the start time to use, in milliseconds.
 297      * @return The newly created LogQuery instance.
 298      */
 299     public static LogQuery withEndTimeMillis(long endTimeMillis) {
 300       return withDefaults().endTimeMillis(endTimeMillis);
 301     }
 302
 303     /**
 304      * Create a {@link LogQuery} with the given end time.
 305      * Shorthand for <code>LogQuery.Builder.withDefaults().endTimeUsec(endTimeUsec);</code>.
 306      * Please read the {@link LogQuery} class javadoc for an explanation of
 307      * how end time is used.
 308      * @param endTimeUsec the start time to use, in microseconds.
 309      * @return The newly created LogQuery instance.
 310      */
 311     public static LogQuery withEndTimeUsec(long endTimeUsec) {
 312       return withDefaults().endTimeUsec(endTimeUsec);
 313     }
 314
 315     /**
 316      * Create a {@link LogQuery} with the given batch size.
 317      * Shorthand for <code>LogQuery.Builder.withDefaults().batchSize(batchSize);</code>.
 318      * Please read the {@link LogQuery} class javadoc for an explanation of
 319      * how batch size is used.
 320      * @param batchSize the batch size to set.
 321      * @return The newly created LogQuery instance.
 322      */
 323     public static LogQuery withBatchSize(int batchSize) {
 324       return withDefaults().batchSize(batchSize);
 325     }
 326
 327     /**
 328      * Create a {@link LogQuery} with the given minimum log level.
 329      * Shorthand for <code>LogQuery.Builder.withDefaults().minLogLevel(minLogLevel);</code>.
 330      * Please read the {@link LogQuery} class javadoc for an explanation of
 331      * how minimum log level is used.
 332      * @param minLogLevel the minimum log level to set.
 333      * @return The newly created LogQuery instance.
 334      */
 335     public static LogQuery withMinLogLevel(LogLevel minLogLevel) {
 336       return withDefaults().minLogLevel(minLogLevel);
 337     }
 338
 339     /**
 340      * Create a {@link LogQuery} with the given include incomplete setting.
 341      * Shorthand for
 342      * <code>LogQuery.Builder.withDefaults().includeIncomplete(includeIncomplete);</code>.
 343      * Please read the {@link LogQuery} class javadoc for an explanation of
 344      * how include incomplete is used.
 345      * @param includeIncomplete the inclusion value to set.
 346      * @return The newly created LogQuery instance.
 347      */
 348     public static LogQuery withIncludeIncomplete(boolean includeIncomplete) {
 349       return withDefaults().includeIncomplete(includeIncomplete);
 350     }
 351
 352     /**
 353      * Create a {@link LogQuery} with include application logs set.
 354      * Shorthand for <code>LogQuery.Builder.withDefaults().includeAppLogs(includeAppLogs);</code>.
 355      * Please read the {@link LogQuery} class javadoc for an explanation of
 356      * the include application logs setting.
 357      * @param includeAppLogs the inclusion value to set.
 358      * @return The newly created LogQuery instance.
 359      */
 360     public static LogQuery withIncludeAppLogs(boolean includeAppLogs) {
 361       return withDefaults().includeAppLogs(includeAppLogs);
 362     }
 363
 364     /**
 365      * Create a {@link LogQuery} with the given major version IDs.
 366      * Shorthand for <code>LogQuery.Builder.withDefaults().majorVersionIds(versionIds);</code>.
 367      * Please read the {@link LogQuery} class javadoc for an explanation of
 368      * how the list of major version ids is used.
 369      * @param versionIds the major version id list to set.
 370      * @return The newly created LogQuery instance.
 371      */
 372     public static LogQuery withMajorVersionIds(List<String> versionIds) {
 373       return withDefaults().majorVersionIds(versionIds);
 374     }
 375
 376     /**
 377      * Create a {@link LogQuery} with the given {@link Version} values.
 378      * Shorthand for
 379      * <code>LogQuery.Builder.withDefaults().versions(versions);</code>.
 380      * Please read the {@link LogQuery} class javadoc for usage information.
 381      * @param versions the list to set.
 382      * @return The newly created LogQuery instance.
 383      */
 384      public static LogQuery withVersions(List<Version> versions) {
 385       return withDefaults().versions(versions);
 386     }
 387
 388     /**
 389      * Create a {@link LogQuery} with the given server and version IDs.
 390      * Shorthand for <code>LogQuery.Builder.withDefaults().serverVersions(serverVersionIds);</code>.
 391      * Please read the {@link LogQuery} class javadoc for an explanation of
 392      * how the list of servers and versions is used.
 393      * @param serverVersionIds the server version id list to set.
 394      * @return The newly created LogQuery instance.
 395      * @deprecated Pending removal, please use {@link #withVersions} instead.
 396      */
 397     @Deprecated
 398     public static LogQuery withServerVersions(List<Pair<String, String>> serverVersionIds) {
 399       return withDefaults().moduleVersions(serverVersionIds);
 400     }
 401
 402     /**
 403      * Create a {@link LogQuery} with the given module and version IDs.
 404      * Shorthand for <code>LogQuery.Builder.withDefaults().moduleVersions(moduleVersionIds);</code>.
 405      * Please read the {@link LogQuery} class javadoc for an explanation of
 406      * how the list of modules and versions is used.
 407      * @param moduleVersionIds the module version id list to set.
 408      * @return The newly created LogQuery instance.
 409      * @deprecated Pending removal, please use {@link #withVersions} instead.
 410      */
 411     @Deprecated
 412     public static LogQuery withModuleVersions(List<Pair<String, String>> moduleVersionIds) {
 413       return withDefaults().moduleVersions(moduleVersionIds);
 414     }
 415
 416     /**
 417      * Create a {@link LogQuery} with the given request IDs.
 418      * Shorthand for <code>LogQuery.Builder.withDefaults().requestIds(requestIds);</code>.
 419      * See the {@link LogQuery} class javadoc for an explanation of
 420      * how the list of request ids is used.
 421      * @param requestIds the request id list to set.
 422      * @return The newly created LogQuery instance.
 423      * @since App Engine 1.7.4.
 424      */
 425     public static LogQuery withRequestIds(List<String> requestIds) {
 426       return withDefaults().requestIds(requestIds);
 427     }
 428
 429     /**
 430      * Helper method for creating a {@link LogQuery} instance with
 431      * default values. Please read the {@link LogQuery} class javadoc for an
 432      * explanation of the defaults.
 433      */
 434     public static LogQuery withDefaults() {
 435       return new LogQuery();
 436     }
 437   }
 438
 439   /**
 440    * Makes a copy of a provided LogQuery.
 441    *
 442    * @return A new LogQuery whose fields are copied from the given LogQuery.
 443    */
 444   @Override
 445   public LogQuery clone() {
 446     LogQuery clone;
 447     try {
 448       clone = (LogQuery) super.clone();
 449     } catch (CloneNotSupportedException e) {
 450       throw new RuntimeException(e);
 451     }
 452
 453     clone.majorVersionIds = new ArrayList<String>(majorVersionIds);
 454     clone.moduleVersions = new ArrayList<Pair<String, String>>(moduleVersions);
 455     clone.requestIds = new ArrayList<String>(requestIds);
 456     clone.versions.addAll(versions);
 457     return clone;
 458   }
 459
 460   /**
 461    * Sets the offset.  Please read the class javadoc for an explanation of
 462    * how offset is used.
 463    * @param offset The offset to set.
 464    * @return {@code this} (for chaining)
 465    */
 466   public LogQuery offset(String offset) {
 467     this.offset = offset;
 468     return this;
 469   }
 470
 471   /**
 472    * Sets the start time to a value in milliseconds.  Please read the class
 473    * javadoc for an explanation of how start time is used.
 474    * @param startTimeMillis The start time to set, in milliseconds.
 475    * @return {@code this} (for chaining)
 476    */
 477   public LogQuery startTimeMillis(long startTimeMillis) {
 478     this.startTimeUsec = startTimeMillis * 1000;
 479     return this;
 480   }
 481
 482   /**
 483    * Sets the start time to a value in microseconds.  Please read the class
 484    * javadoc for an explanation of how start time is used.
 485    * @param startTimeUsec The start time to set, in microseconds.
 486    * @return {@code this} (for chaining)
 487    */
 488   public LogQuery startTimeUsec(long startTimeUsec) {
 489     this.startTimeUsec = startTimeUsec;
 490     return this;
 491   }
 492
 493   /**
 494    * Sets the end time to a value in milliseconds.  Please read the class
 495    * javadoc for an explanation of how end time is used.
 496    * @param endTimeMillis The end time to set, in milliseconds.
 497    * @return {@code this} (for chaining)
 498    */
 499   public LogQuery endTimeMillis(long endTimeMillis) {
 500     this.endTimeUsec = endTimeMillis * 1000;
 501     return this;
 502   }
 503
 504   /**
 505    * Sets the end time to a value in microseconds.  Please read the class
 506    * javadoc for an explanation of how end time is used.
 507    * @param endTimeUsec The end time to set, in microseconds.
 508    * @return {@code this} (for chaining)
 509    */
 510   public LogQuery endTimeUsec(long endTimeUsec) {
 511     this.endTimeUsec = endTimeUsec;
 512     return this;
 513   }
 514
 515   /**
 516    * Sets the batch size.  Please read the class javadoc for an explanation of
 517    * how batch size is used.
 518    * @param batchSize The batch size to set.  Must be greater than 0.
 519    * @return {@code this} (for chaining)
 520    */
 521   public LogQuery batchSize(int batchSize) {
 522     if (batchSize < 1) {
 523       throw new IllegalArgumentException("batchSize must be greater than zero");
 524     }
 525
 526     this.batchSize = batchSize;
 527     return this;
 528   }
 529
 530   /**
 531    * Sets the minimum log level.  Please read the class javadoc for an
 532    * explanation of how minimum log level is used.
 533    * @param minLogLevel The minimum log level to set.
 534    * @return {@code this} (for chaining)
 535    */
 536   public LogQuery minLogLevel(LogLevel minLogLevel) {
 537     this.minLogLevel = minLogLevel;
 538     return this;
 539   }
 540
 541   /**
 542    * Sets include incomplete.  Please read the class javadoc for an
 543    * explanation of how include incomplete is used.
 544    * @param includeIncomplete The value to set.
 545    * @return {@code this} (for chaining)
 546    */
 547   public LogQuery includeIncomplete(boolean includeIncomplete) {
 548     this.includeIncomplete = includeIncomplete;
 549     return this;
 550   }
 551
 552   /**
 553    * Sets include application logs.  Please read the class javadoc for an
 554    * explanation of how include application logs is used.
 555    * @param includeAppLogs The value to set.
 556    * @return {@code this} (for chaining)
 557    */
 558   public LogQuery includeAppLogs(boolean includeAppLogs) {
 559     this.includeAppLogs = includeAppLogs;
 560     return this;
 561   }
 562
 563   /**
 564    * Sets the major version identifiers to query.  Please read the class
 565    * javadoc for an explanation of how major versions are used.
 566    * @param versionIds The major version identifier list to set.
 567    * @return {@code this} (for chaining)
 568    */
 569   public LogQuery majorVersionIds(List<String> versionIds) {
 570     if (!this.moduleVersions.isEmpty()) {
 571       throw new IllegalArgumentException(
 572           "The moduleVersions() method has already been called, only one of majorVersionIds() " +
 573           "or moduleVersions() may be called on a LogQuery instance.");
 574     }
 575
 576     if (!versions.isEmpty()) {
 577       throw new IllegalStateException(
 578           "LogQuery.majorVersionIds may not be called after LogQuery.versions.");
 579     }
 580
 581     for (String versionId : versionIds) {
 582       Matcher matcher = VERSION_PATTERN.matcher(versionId);
 583       if (!matcher.matches()) {
 584         throw new IllegalArgumentException("versionIds must only contain valid " +
 585           "major version identifiers. Version " + versionId + " is not a valid " +
 586           "major version identifier.");
 587       }
 588     }
 589
 590     this.majorVersionIds = versionIds;
 591     return this;
 592   }
 593
 594   /**
 595    * Sets the module and version identifiers to query.  Please read the class
 596    * javadoc for an explanation of how Modules and Versions are used.
 597    * @param moduleVersions The list of Modules and Versions to set.
 598    * @return {@code this} (for chaining)
 599    * @deprecated Pending removal, please use {@link #versions} instead.
 600    */
 601   @Deprecated
 602   public LogQuery moduleVersions(List<Pair<String, String>> moduleVersions) {
 603     if (!this.majorVersionIds.isEmpty()) {
 604       throw new IllegalArgumentException(
 605           "The majorVersionIds() method has already been called, only one of majorVersionIds() " +
 606           "or moduleVersions() may be called on a LogQuery instance.");
 607     }
 608
 609     if (!versions.isEmpty()) {
 610       throw new IllegalStateException(
 611           "LogQuery.moduleVersions may not be called after LogQuery.versions.");
 612     }
 613
 614     for (Pair<String, String> moduleVersion : moduleVersions) {
 615       Matcher matcher = VERSION_PATTERN.matcher(moduleVersion.first);
 616       if (!matcher.matches()) {
 617         throw new IllegalArgumentException("moduleVersions must only contain valid " +
 618           "module identifiers. Module " + moduleVersion.first + " is not a valid " +
 619           "module identifier.");
 620       }
 621       matcher = VERSION_PATTERN.matcher(moduleVersion.second);
 622       if (!matcher.matches()) {
 623         throw new IllegalArgumentException("moduleVersions must only contain valid " +
 624           "version identifiers. Version " + moduleVersion.second + " is not a valid " +
 625           "version identifier.");
 626       }
 627     }
 628
 629     this.moduleVersions = moduleVersions;
 630     return this;
 631   }
 632
 633   /**
 634    * Sets the module and version identifiers to query.  Please read the class
 635    * javadoc for an explanation of how Modules and Versions are used.
 636    * @param serverVersions The list of Modules and Versions to set.
 637    * @return {@code this} (for chaining)
 638    * @deprecated Pending removal, please use {@link #versions} instead.
 639    */
 640   @Deprecated
 641   public LogQuery serverVersions(List<Pair<String, String>> serverVersions) {
 642     return moduleVersions(serverVersions);
 643   }
 644
 645   /**
 646    * Restricts the query to log records for the specified module versions.
 647    *
 648    * Please read the class javadoc for usage information.
 649    *
 650    * @param versions The list of module versions to query.
 651    * @return {@code this} (for chaining)
 652    */
 653   public LogQuery versions(List<Version> versions) {
 654     if (!this.majorVersionIds.isEmpty()) {
 655       throw new IllegalStateException(
 656           "LogQuery.versions may not be called after LogQuery.majorVersionIds.");
 657     }
 658
 659     if (!moduleVersions.isEmpty()) {
 660       throw new IllegalStateException(
 661           "LogQuery.versions may not be called after LogQuery.moduleVersions.");
 662     }
 663
 664     if (!requestIds.isEmpty()) {
 665       throw new IllegalStateException(
 666           "LogQuery.versions may not be called after LogQuery.requestIds.");
 667     }
 668
 669     this.versions.clear();
 670     this.versions.addAll(versions);
 671     return this;
 672   }
 673
 674   /**
 675    * Sets the list of request ids to query.  See the class javadoc for an
 676    * explanation of how request ids are used.
 677    * @param requestIds The request id list to set.
 678    * @return {@code this} (for chaining)
 679    */
 680   public LogQuery requestIds(List<String> requestIds) {
 681     if (!versions.isEmpty()) {
 682       throw new IllegalStateException(
 683           "LogQuery.requestIds may not be called after LogQuery.versions.");
 684     }
 685
 686     Set<String> seen = new HashSet<String>();
 687     for (String requestId : requestIds) {
 688       if (!seen.add(requestId)) {
 689         throw new IllegalArgumentException("requestIds must be unique.");
 690       }
 691
 692       Matcher matcher = REQUEST_ID_PATTERN.matcher(requestId);
 693       if (!matcher.matches()) {
 694         throw new IllegalArgumentException("requestIds must only contain valid " +
 695           "request ids. " + requestId + " is not a valid " +
 696           "request id.");
 697       }
 698     }
 699
 700     this.requestIds = requestIds;
 701     return this;
 702   }
 703
 704   /**
 705    * @return The offset, or {@code null} if none was provided.
 706    */
 707   public String getOffset() {
 708     return offset;
 709   }
 710
 711   /**
 712    * @return The batch size, or {@code null} if none was provided.
 713    */
 714   public Integer getBatchSize() {
 715     return batchSize;
 716   }
 717
 718   /**
 719    * @return The end time in milliseconds, or {@code null} if none was provided.
 720    */
 721   public Long getEndTimeMillis() {
 722     return endTimeUsec != null ? endTimeUsec / 1000 : null;
 723   }
 724
 725   /**
 726    * @return The end time in microseconds, or {@code null} if none was provided.
 727    */
 728   public Long getEndTimeUsec() {
 729     return endTimeUsec;
 730   }
 731
 732   /**
 733    * @return Whether or not application logs should be returned.
 734    */
 735   public Boolean getIncludeAppLogs() {
 736     return includeAppLogs;
 737   }
 738
 739   /**
 740    * @return Whether or not incomplete request logs should be returned.
 741    */
 742   public Boolean getIncludeIncomplete() {
 743     return includeIncomplete;
 744   }
 745
 746   /**
 747    * @return The minimum log level, or {@code null} if none was provided.
 748    */
 749   public LogLevel getMinLogLevel() {
 750     return minLogLevel;
 751   }
 752
 753   /**
 754    * @return The start time in milliseconds, or {@code null} if none was provided.
 755    */
 756   public Long getStartTimeMillis() {
 757     return startTimeUsec != null ? startTimeUsec / 1000 : null;
 758   }
 759
 760   /**
 761    * @return The start time in microseconds, or {@code null} if none was provided.
 762    */
 763   public Long getStartTimeUsec() {
 764     return startTimeUsec;
 765   }
 766
 767   /**
 768    * @return The list of major app versions that should be queried over, or
 769    * an empty list if none were set.
 770    */
 771   public List<String> getMajorVersionIds() {
 772     return majorVersionIds;
 773   }
 774
 775   /**
 776    * @return The list of server versions for the application that should be
 777    * queried, may be empty.
 778    * @deprecated Pending removal, please use {@link #versions} instead.
 779    */
 780   @Deprecated
 781   public List<Pair<String, String>> getServerVersions() {
 782     return getModuleVersions();
 783   }
 784
 785   /**
 786    * @return The list of module versions for the application that should be
 787    * queried over, may be empty.
 788    * @deprecated Pending removal, please use {@link #versions} instead.
 789    */
 790   @Deprecated
 791   public List<Pair<String, String>> getModuleVersions() {
 792     return moduleVersions;
 793   }
 794
 795   /**
 796    * @return The list possibly empty list of module versions that should be queried over.
 797    */
 798   public List<Version> getVersions() {
 799     ImmutableList.Builder<Version> builder = ImmutableList.builder();
 800     return builder.addAll(versions).build();
 801   }
 802
 803   /**
 804    * @return The list of request ids that should be queried over, or
 805    * {@code null} if none were set.
 806    */
 807   public List<String> getRequestIds() {
 808     return requestIds;
 809   }
 810 }