001/* 002 * Copyright (C) 2011 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.cache; 016 017import static com.google.common.base.Preconditions.checkArgument; 018import static com.google.common.base.Strings.isNullOrEmpty; 019 020import com.google.common.annotations.GwtIncompatible; 021import com.google.common.annotations.VisibleForTesting; 022import com.google.common.base.MoreObjects; 023import com.google.common.base.Objects; 024import com.google.common.base.Splitter; 025import com.google.common.cache.LocalCache.Strength; 026import com.google.common.collect.ImmutableList; 027import com.google.common.collect.ImmutableMap; 028import java.util.List; 029import java.util.Locale; 030import java.util.concurrent.TimeUnit; 031import javax.annotation.CheckForNull; 032import org.checkerframework.checker.nullness.qual.Nullable; 033 034/** 035 * A specification of a {@link CacheBuilder} configuration. 036 * 037 * <p>{@code CacheBuilderSpec} supports parsing configuration off of a string, which makes it 038 * especially useful for command-line configuration of a {@code CacheBuilder}. 039 * 040 * <p>The string syntax is a series of comma-separated keys or key-value pairs, each corresponding 041 * to a {@code CacheBuilder} method. 042 * 043 * <ul> 044 * <li>{@code concurrencyLevel=[integer]}: sets {@link CacheBuilder#concurrencyLevel}. 045 * <li>{@code initialCapacity=[integer]}: sets {@link CacheBuilder#initialCapacity}. 046 * <li>{@code maximumSize=[long]}: sets {@link CacheBuilder#maximumSize}. 047 * <li>{@code maximumWeight=[long]}: sets {@link CacheBuilder#maximumWeight}. 048 * <li>{@code expireAfterAccess=[duration]}: sets {@link CacheBuilder#expireAfterAccess}. 049 * <li>{@code expireAfterWrite=[duration]}: sets {@link CacheBuilder#expireAfterWrite}. 050 * <li>{@code refreshAfterWrite=[duration]}: sets {@link CacheBuilder#refreshAfterWrite}. 051 * <li>{@code weakKeys}: sets {@link CacheBuilder#weakKeys}. 052 * <li>{@code softValues}: sets {@link CacheBuilder#softValues}. 053 * <li>{@code weakValues}: sets {@link CacheBuilder#weakValues}. 054 * <li>{@code recordStats}: sets {@link CacheBuilder#recordStats}. 055 * </ul> 056 * 057 * <p>The set of supported keys will grow as {@code CacheBuilder} evolves, but existing keys will 058 * never be removed. 059 * 060 * <p>Durations are represented by an integer, followed by one of "d", "h", "m", or "s", 061 * representing days, hours, minutes, or seconds respectively. (There is currently no syntax to 062 * request expiration in milliseconds, microseconds, or nanoseconds.) 063 * 064 * <p>Whitespace before and after commas and equal signs is ignored. Keys may not be repeated; it is 065 * also illegal to use the following pairs of keys in a single value: 066 * 067 * <ul> 068 * <li>{@code maximumSize} and {@code maximumWeight} 069 * <li>{@code softValues} and {@code weakValues} 070 * </ul> 071 * 072 * <p>{@code CacheBuilderSpec} does not support configuring {@code CacheBuilder} methods with 073 * non-value parameters. These must be configured in code. 074 * 075 * <p>A new {@code CacheBuilder} can be instantiated from a {@code CacheBuilderSpec} using {@link 076 * CacheBuilder#from(CacheBuilderSpec)} or {@link CacheBuilder#from(String)}. 077 * 078 * @author Adam Winer 079 * @since 12.0 080 */ 081@SuppressWarnings("GoodTime") // lots of violations (nanosecond math) 082@GwtIncompatible 083@ElementTypesAreNonnullByDefault 084public final class CacheBuilderSpec { 085 /** Parses a single value. */ 086 private interface ValueParser { 087 void parse(CacheBuilderSpec spec, String key, @CheckForNull String value); 088 } 089 090 /** Splits each key-value pair. */ 091 private static final Splitter KEYS_SPLITTER = Splitter.on(',').trimResults(); 092 093 /** Splits the key from the value. */ 094 private static final Splitter KEY_VALUE_SPLITTER = Splitter.on('=').trimResults(); 095 096 /** Map of names to ValueParser. */ 097 private static final ImmutableMap<String, ValueParser> VALUE_PARSERS = 098 ImmutableMap.<String, ValueParser>builder() 099 .put("initialCapacity", new InitialCapacityParser()) 100 .put("maximumSize", new MaximumSizeParser()) 101 .put("maximumWeight", new MaximumWeightParser()) 102 .put("concurrencyLevel", new ConcurrencyLevelParser()) 103 .put("weakKeys", new KeyStrengthParser(Strength.WEAK)) 104 .put("softValues", new ValueStrengthParser(Strength.SOFT)) 105 .put("weakValues", new ValueStrengthParser(Strength.WEAK)) 106 .put("recordStats", new RecordStatsParser()) 107 .put("expireAfterAccess", new AccessDurationParser()) 108 .put("expireAfterWrite", new WriteDurationParser()) 109 .put("refreshAfterWrite", new RefreshDurationParser()) 110 .put("refreshInterval", new RefreshDurationParser()) 111 .buildOrThrow(); 112 113 @VisibleForTesting @CheckForNull Integer initialCapacity; 114 @VisibleForTesting @CheckForNull Long maximumSize; 115 @VisibleForTesting @CheckForNull Long maximumWeight; 116 @VisibleForTesting @CheckForNull Integer concurrencyLevel; 117 @VisibleForTesting @CheckForNull Strength keyStrength; 118 @VisibleForTesting @CheckForNull Strength valueStrength; 119 @VisibleForTesting @CheckForNull Boolean recordStats; 120 @VisibleForTesting long writeExpirationDuration; 121 @VisibleForTesting @CheckForNull TimeUnit writeExpirationTimeUnit; 122 @VisibleForTesting long accessExpirationDuration; 123 @VisibleForTesting @CheckForNull TimeUnit accessExpirationTimeUnit; 124 @VisibleForTesting long refreshDuration; 125 @VisibleForTesting @CheckForNull TimeUnit refreshTimeUnit; 126 /** Specification; used for toParseableString(). */ 127 private final String specification; 128 129 private CacheBuilderSpec(String specification) { 130 this.specification = specification; 131 } 132 133 /** 134 * Creates a CacheBuilderSpec from a string. 135 * 136 * @param cacheBuilderSpecification the string form 137 */ 138 public static CacheBuilderSpec parse(String cacheBuilderSpecification) { 139 CacheBuilderSpec spec = new CacheBuilderSpec(cacheBuilderSpecification); 140 if (!cacheBuilderSpecification.isEmpty()) { 141 for (String keyValuePair : KEYS_SPLITTER.split(cacheBuilderSpecification)) { 142 List<String> keyAndValue = ImmutableList.copyOf(KEY_VALUE_SPLITTER.split(keyValuePair)); 143 checkArgument(!keyAndValue.isEmpty(), "blank key-value pair"); 144 checkArgument( 145 keyAndValue.size() <= 2, 146 "key-value pair %s with more than one equals sign", 147 keyValuePair); 148 149 // Find the ValueParser for the current key. 150 String key = keyAndValue.get(0); 151 ValueParser valueParser = VALUE_PARSERS.get(key); 152 checkArgument(valueParser != null, "unknown key %s", key); 153 154 String value = keyAndValue.size() == 1 ? null : keyAndValue.get(1); 155 valueParser.parse(spec, key, value); 156 } 157 } 158 159 return spec; 160 } 161 162 /** Returns a CacheBuilderSpec that will prevent caching. */ 163 public static CacheBuilderSpec disableCaching() { 164 // Maximum size of zero is one way to block caching 165 return CacheBuilderSpec.parse("maximumSize=0"); 166 } 167 168 /** Returns a CacheBuilder configured according to this instance's specification. */ 169 CacheBuilder<Object, Object> toCacheBuilder() { 170 CacheBuilder<Object, Object> builder = CacheBuilder.newBuilder(); 171 if (initialCapacity != null) { 172 builder.initialCapacity(initialCapacity); 173 } 174 if (maximumSize != null) { 175 builder.maximumSize(maximumSize); 176 } 177 if (maximumWeight != null) { 178 builder.maximumWeight(maximumWeight); 179 } 180 if (concurrencyLevel != null) { 181 builder.concurrencyLevel(concurrencyLevel); 182 } 183 if (keyStrength != null) { 184 switch (keyStrength) { 185 case WEAK: 186 builder.weakKeys(); 187 break; 188 default: 189 throw new AssertionError(); 190 } 191 } 192 if (valueStrength != null) { 193 switch (valueStrength) { 194 case SOFT: 195 builder.softValues(); 196 break; 197 case WEAK: 198 builder.weakValues(); 199 break; 200 default: 201 throw new AssertionError(); 202 } 203 } 204 if (recordStats != null && recordStats) { 205 builder.recordStats(); 206 } 207 if (writeExpirationTimeUnit != null) { 208 builder.expireAfterWrite(writeExpirationDuration, writeExpirationTimeUnit); 209 } 210 if (accessExpirationTimeUnit != null) { 211 builder.expireAfterAccess(accessExpirationDuration, accessExpirationTimeUnit); 212 } 213 if (refreshTimeUnit != null) { 214 builder.refreshAfterWrite(refreshDuration, refreshTimeUnit); 215 } 216 217 return builder; 218 } 219 220 /** 221 * Returns a string that can be used to parse an equivalent {@code CacheBuilderSpec}. The order 222 * and form of this representation is not guaranteed, except that reparsing its output will 223 * produce a {@code CacheBuilderSpec} equal to this instance. 224 */ 225 public String toParsableString() { 226 return specification; 227 } 228 229 /** 230 * Returns a string representation for this CacheBuilderSpec instance. The form of this 231 * representation is not guaranteed. 232 */ 233 @Override 234 public String toString() { 235 return MoreObjects.toStringHelper(this).addValue(toParsableString()).toString(); 236 } 237 238 @Override 239 public int hashCode() { 240 return Objects.hashCode( 241 initialCapacity, 242 maximumSize, 243 maximumWeight, 244 concurrencyLevel, 245 keyStrength, 246 valueStrength, 247 recordStats, 248 durationInNanos(writeExpirationDuration, writeExpirationTimeUnit), 249 durationInNanos(accessExpirationDuration, accessExpirationTimeUnit), 250 durationInNanos(refreshDuration, refreshTimeUnit)); 251 } 252 253 @Override 254 public boolean equals(@CheckForNull Object obj) { 255 if (this == obj) { 256 return true; 257 } 258 if (!(obj instanceof CacheBuilderSpec)) { 259 return false; 260 } 261 CacheBuilderSpec that = (CacheBuilderSpec) obj; 262 return Objects.equal(initialCapacity, that.initialCapacity) 263 && Objects.equal(maximumSize, that.maximumSize) 264 && Objects.equal(maximumWeight, that.maximumWeight) 265 && Objects.equal(concurrencyLevel, that.concurrencyLevel) 266 && Objects.equal(keyStrength, that.keyStrength) 267 && Objects.equal(valueStrength, that.valueStrength) 268 && Objects.equal(recordStats, that.recordStats) 269 && Objects.equal( 270 durationInNanos(writeExpirationDuration, writeExpirationTimeUnit), 271 durationInNanos(that.writeExpirationDuration, that.writeExpirationTimeUnit)) 272 && Objects.equal( 273 durationInNanos(accessExpirationDuration, accessExpirationTimeUnit), 274 durationInNanos(that.accessExpirationDuration, that.accessExpirationTimeUnit)) 275 && Objects.equal( 276 durationInNanos(refreshDuration, refreshTimeUnit), 277 durationInNanos(that.refreshDuration, that.refreshTimeUnit)); 278 } 279 280 /** 281 * Converts an expiration duration/unit pair into a single Long for hashing and equality. Uses 282 * nanos to match CacheBuilder implementation. 283 */ 284 @CheckForNull 285 private static Long durationInNanos(long duration, @CheckForNull TimeUnit unit) { 286 return (unit == null) ? null : unit.toNanos(duration); 287 } 288 289 /** Base class for parsing integers. */ 290 abstract static class IntegerParser implements ValueParser { 291 protected abstract void parseInteger(CacheBuilderSpec spec, int value); 292 293 @Override 294 public void parse(CacheBuilderSpec spec, String key, @Nullable String value) { 295 if (isNullOrEmpty(value)) { 296 throw new IllegalArgumentException("value of key " + key + " omitted"); 297 } 298 try { 299 parseInteger(spec, Integer.parseInt(value)); 300 } catch (NumberFormatException e) { 301 throw new IllegalArgumentException( 302 format("key %s value set to %s, must be integer", key, value), e); 303 } 304 } 305 } 306 307 /** Base class for parsing integers. */ 308 abstract static class LongParser implements ValueParser { 309 protected abstract void parseLong(CacheBuilderSpec spec, long value); 310 311 @Override 312 public void parse(CacheBuilderSpec spec, String key, @Nullable String value) { 313 if (isNullOrEmpty(value)) { 314 throw new IllegalArgumentException("value of key " + key + " omitted"); 315 } 316 try { 317 parseLong(spec, Long.parseLong(value)); 318 } catch (NumberFormatException e) { 319 throw new IllegalArgumentException( 320 format("key %s value set to %s, must be integer", key, value), e); 321 } 322 } 323 } 324 325 /** Parse initialCapacity */ 326 static class InitialCapacityParser extends IntegerParser { 327 @Override 328 protected void parseInteger(CacheBuilderSpec spec, int value) { 329 checkArgument( 330 spec.initialCapacity == null, 331 "initial capacity was already set to ", 332 spec.initialCapacity); 333 spec.initialCapacity = value; 334 } 335 } 336 337 /** Parse maximumSize */ 338 static class MaximumSizeParser extends LongParser { 339 @Override 340 protected void parseLong(CacheBuilderSpec spec, long value) { 341 checkArgument(spec.maximumSize == null, "maximum size was already set to ", spec.maximumSize); 342 checkArgument( 343 spec.maximumWeight == null, "maximum weight was already set to ", spec.maximumWeight); 344 spec.maximumSize = value; 345 } 346 } 347 348 /** Parse maximumWeight */ 349 static class MaximumWeightParser extends LongParser { 350 @Override 351 protected void parseLong(CacheBuilderSpec spec, long value) { 352 checkArgument( 353 spec.maximumWeight == null, "maximum weight was already set to ", spec.maximumWeight); 354 checkArgument(spec.maximumSize == null, "maximum size was already set to ", spec.maximumSize); 355 spec.maximumWeight = value; 356 } 357 } 358 359 /** Parse concurrencyLevel */ 360 static class ConcurrencyLevelParser extends IntegerParser { 361 @Override 362 protected void parseInteger(CacheBuilderSpec spec, int value) { 363 checkArgument( 364 spec.concurrencyLevel == null, 365 "concurrency level was already set to ", 366 spec.concurrencyLevel); 367 spec.concurrencyLevel = value; 368 } 369 } 370 371 /** Parse weakKeys */ 372 static class KeyStrengthParser implements ValueParser { 373 private final Strength strength; 374 375 public KeyStrengthParser(Strength strength) { 376 this.strength = strength; 377 } 378 379 @Override 380 public void parse(CacheBuilderSpec spec, String key, @CheckForNull String value) { 381 checkArgument(value == null, "key %s does not take values", key); 382 checkArgument(spec.keyStrength == null, "%s was already set to %s", key, spec.keyStrength); 383 spec.keyStrength = strength; 384 } 385 } 386 387 /** Parse weakValues and softValues */ 388 static class ValueStrengthParser implements ValueParser { 389 private final Strength strength; 390 391 public ValueStrengthParser(Strength strength) { 392 this.strength = strength; 393 } 394 395 @Override 396 public void parse(CacheBuilderSpec spec, String key, @CheckForNull String value) { 397 checkArgument(value == null, "key %s does not take values", key); 398 checkArgument( 399 spec.valueStrength == null, "%s was already set to %s", key, spec.valueStrength); 400 401 spec.valueStrength = strength; 402 } 403 } 404 405 /** Parse recordStats */ 406 static class RecordStatsParser implements ValueParser { 407 408 @Override 409 public void parse(CacheBuilderSpec spec, String key, @CheckForNull String value) { 410 checkArgument(value == null, "recordStats does not take values"); 411 checkArgument(spec.recordStats == null, "recordStats already set"); 412 spec.recordStats = true; 413 } 414 } 415 416 /** Base class for parsing times with durations */ 417 abstract static class DurationParser implements ValueParser { 418 protected abstract void parseDuration(CacheBuilderSpec spec, long duration, TimeUnit unit); 419 420 @Override 421 public void parse(CacheBuilderSpec spec, String key, @CheckForNull String value) { 422 if (isNullOrEmpty(value)) { 423 throw new IllegalArgumentException("value of key " + key + " omitted"); 424 } 425 try { 426 char lastChar = value.charAt(value.length() - 1); 427 TimeUnit timeUnit; 428 switch (lastChar) { 429 case 'd': 430 timeUnit = TimeUnit.DAYS; 431 break; 432 case 'h': 433 timeUnit = TimeUnit.HOURS; 434 break; 435 case 'm': 436 timeUnit = TimeUnit.MINUTES; 437 break; 438 case 's': 439 timeUnit = TimeUnit.SECONDS; 440 break; 441 default: 442 throw new IllegalArgumentException( 443 format("key %s invalid unit: was %s, must end with one of [dhms]", key, value)); 444 } 445 446 long duration = Long.parseLong(value.substring(0, value.length() - 1)); 447 parseDuration(spec, duration, timeUnit); 448 } catch (NumberFormatException e) { 449 throw new IllegalArgumentException( 450 format("key %s value set to %s, must be integer", key, value)); 451 } 452 } 453 } 454 455 /** Parse expireAfterAccess */ 456 static class AccessDurationParser extends DurationParser { 457 @Override 458 protected void parseDuration(CacheBuilderSpec spec, long duration, TimeUnit unit) { 459 checkArgument(spec.accessExpirationTimeUnit == null, "expireAfterAccess already set"); 460 spec.accessExpirationDuration = duration; 461 spec.accessExpirationTimeUnit = unit; 462 } 463 } 464 465 /** Parse expireAfterWrite */ 466 static class WriteDurationParser extends DurationParser { 467 @Override 468 protected void parseDuration(CacheBuilderSpec spec, long duration, TimeUnit unit) { 469 checkArgument(spec.writeExpirationTimeUnit == null, "expireAfterWrite already set"); 470 spec.writeExpirationDuration = duration; 471 spec.writeExpirationTimeUnit = unit; 472 } 473 } 474 475 /** Parse refreshAfterWrite */ 476 static class RefreshDurationParser extends DurationParser { 477 @Override 478 protected void parseDuration(CacheBuilderSpec spec, long duration, TimeUnit unit) { 479 checkArgument(spec.refreshTimeUnit == null, "refreshAfterWrite already set"); 480 spec.refreshDuration = duration; 481 spec.refreshTimeUnit = unit; 482 } 483 } 484 485 private static String format(String format, Object... args) { 486 return String.format(Locale.ROOT, format, args); 487 } 488}