Merge branch 'release/0.0.4'

euler-projects · May 13, 2017 · 889d366 · 889d366
2 parents f3fac6c + 7624ed0
commit 889d366
Show file tree

Hide file tree

Showing 9 changed files with 128 additions and 49 deletions.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 cFrost Sun 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,7 +1,16 @@
-## Status
-
-### latest
 [![Build Status](https://ci.eulerproject.io/job/euler-cache-latest-jdk7/badge/icon)](https://ci.eulerproject.io/job/euler-cache-latest-jdk7)
+[![GitHub issues](https://img.shields.io/github/issues/euler-projects/euler-cache.svg)](https://github.com/euler-projects/euler-cache/issues)
+[![GitHub release](https://img.shields.io/github/release/euler-projects/euler-cache.svg)](https://github.com/euler-projects/euler-cache/releases)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.eulerframework/euler-cache/badge.svg)](https://maven-badges.herokuapp.com/maven-central/net.eulerframework/euler-cache)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/euler-projects/euler-cache/master/LICENSE)
+
+## About
+In Memory Object Cache
+
+Visit [eulerproject.io][] for more info.
+
+## License
+This project is released under the [MIT License][].
 
-### stable
-[![Build Status](https://ci.eulerproject.io/job/euler-cache-stable-jdk7/badge/icon)](https://ci.eulerproject.io/job/euler-cache-stable-jdk7)
+[MIT License]: https://opensource.org/licenses/MIT
+[eulerproject.io]: https://eulerproject.io
diff --git a/pom.xml b/pom.xml
@@ -6,11 +6,11 @@
         <groupId>net.eulerframework</groupId>
         <artifactId>euler-parent</artifactId>
         <version>1</version>
-        <relativePath></relativePath>
+        <relativePath/>
     </parent>
 
     <artifactId>euler-cache</artifactId>
-    <version>0.0.3</version>
+    <version>0.0.4</version>
     <name>euler-cache</name>
     <url>https://eulerproject.io</url>
     <description>In Memory Object Cache</description>

diff --git a/src/main/java/net/eulerframework/cache/inMemoryCache/AbstractObjectCache.java b/src/main/java/net/eulerframework/cache/inMemoryCache/AbstractObjectCache.java
@@ -24,8 +24,8 @@
  * For more information, please visit the following website
  *
  * https://eulerproject.io
- * https://github.com/euler-projects/euler-framework
- * http://cfrost.net
+ * https://github.com/euler-projects/euler-cache
+ * https://cfrost.net
  */
 package net.eulerframework.cache.inMemoryCache;
 
@@ -49,11 +49,10 @@ public abstract class AbstractObjectCache<KEY_T, DATA_T> {
     protected ReentrantLock cacheWriteLock = new ReentrantLock();
 
     /**
-     * 向缓存添加缓存对象<br>
-     * 如果缓存已被其他线程锁定,则放弃添加,返回<code>false</code>
+     * 向缓存添加缓存对象,如果缓存已被其他线程锁定,则放弃添加,返回{@code false}
      * @param key 缓存索引键值
      * @param data 缓存对象
-     * @return 成功返回<code>true</code>;失败返回<code>false</code>
+     * @return 成功返回{@code true};失败返回{@code false}
      */
     public boolean put(KEY_T key, DATA_T data) {
         if(!this.isEnable())
@@ -72,10 +71,9 @@ public boolean put(KEY_T key, DATA_T data) {
     }
 
     /**
-     * 删除缓存对象<br>
-     * 如果缓存已被其他线程锁定,则放弃删除,返回<code>false</code>
+     * 删除缓存对象,如果缓存已被其他线程锁定,则放弃删除,返回{@code false}
      * @param key 缓存索引键值
-     * @return 成功返回<code>true</code>;失败返回<code>false</code>
+     * @return 成功返回{@code true};失败返回{@code false}
      */
     public boolean remove(KEY_T key) {
         if(this.cacheWriteLock.tryLock()) {
@@ -90,9 +88,8 @@ public boolean remove(KEY_T key) {
     }
 
     /**
-     * 清除所有缓存对象<br>
-     * 如果缓存已被其他线程锁定,则放弃清除,返回<code>false</code>
-     * @return 成功返回<code>true</code>;失败返回<code>false</code>
+     * 清除所有缓存对象,如果缓存已被其他线程锁定,则放弃清除,返回{@code false}
+     * @return 成功返回{@code true};失败返回{@code false}
      */
     public boolean clear() {
         if(this.cacheWriteLock.tryLock()) {
@@ -107,16 +104,15 @@ public boolean clear() {
     }
 
     /**
-     * 清理缓存<br>
-     * 尝试删除所有过期缓存对象
+     * 清理缓存,尝试删除所有过期缓存对象
      */
     public void clean() {
         Set<KEY_T> keySet = this.dataMap.keySet();
         Set<KEY_T> keySetNeedRemove = new HashSet<>();
         for(KEY_T key : keySet) {
             DataStore<DATA_T> storedData = this.dataMap.get(key);
 
-            if(this.isTimeout(storedData)) {
+            if(this.isExpired(storedData)) {
                 keySetNeedRemove.add(key);
 
                 this.logger.info("Data key = " + key + " was time out and will be removed.");
@@ -132,35 +128,61 @@ public void clean() {
     /**
      * 查询缓存对象
      * @param key 缓存索引键值
-     * @return 缓存对象,未查到或过期返回<code>null</code>
+     * @return 缓存对象
+     * @throws DataNotFoundException 缓存对象不存在或已过期
      */
-    public DATA_T get(KEY_T key) {
-        if(!this.isEnable())
-            return null;
-
+    public DATA_T get(KEY_T key) throws DataNotFoundException {
+        if(!this.isEnable()) {
+            throw new DataNotFoundException();            
+        }
+
         DataStore<DATA_T> storedData = this.dataMap.get(key);
 
-        if(storedData == null)
-            return null;
+        if(storedData == null) {
+            throw new DataNotFoundException();            
+        }   
 
-        if(this.isTimeout(storedData)) {
+        if(this.isExpired(storedData)) {
             this.remove(key);
-            return null;
+            throw new DataNotFoundException();
         }
 
         return storedData.getData();
     }
+
+    /**
+     * 查询缓存对象
+     * 
+     * <p>在缓存对象不存在或已过期时,会调用{@link DataGetter#getData(Object)}获取数据,并更新缓存池</p>
+     * 
+     * @param key 缓存对象键值
+     * @param dataGetter 缓存对象不存在或已过期时的数据读取回调
+     * @return 缓存对象
+     */
+    public DATA_T get(KEY_T key, DataGetter<KEY_T, DATA_T> dataGetter) {
+        DATA_T data;
+
+        try {
+            data = this.get(key);
+        } catch (DataNotFoundException e) {
+            // 缓存对象不存在或过期,从实际位置查询
+            data = dataGetter.getData(key);
+            this.put(key, data);
+        }
+
+        return data;
+    }
 
     /**
      * 判断缓存对象是否过期
-     * @param storedData
-     * @return
+     * @param storedData 待判断的缓存对象存储类
+     * @return 过期返回{@code true}, 未过期返回{@code false}
      */
-    public abstract boolean isTimeout(DataStore<DATA_T> storedData);
+    public abstract boolean isExpired(DataStore<DATA_T> storedData);
 
     /**
      * 判断缓存是否启用
-     * @return
+     * @return 启用返回{@code true}, 未启用返回{@code false}
      */
     public abstract boolean isEnable();
 
@@ -181,4 +203,17 @@ public long getAddTime() {
             return addTime;
         }
     }
+
+    public interface DataGetter<KEY_T, DATA_T> {
+
+        /**
+         * 从数据源读取数据
+         * 
+         * <p>当被查询的缓存对象不存在或已过期时回调用该方法, 该方法中应有真实数据的读取逻辑</p>
+         * 
+         * @param key 缓存对象键值
+         * @return 读取到的最新数据
+         */
+        DATA_T getData(KEY_T key);
+    }
 }
diff --git a/src/main/java/net/eulerframework/cache/inMemoryCache/CacheTimerObjectCache.java b/src/main/java/net/eulerframework/cache/inMemoryCache/CacheTimerObjectCache.java
@@ -24,8 +24,8 @@
  * For more information, please visit the following website
  *
  * https://eulerproject.io
- * https://github.com/euler-projects/euler-framework
- * http://cfrost.net
+ * https://github.com/euler-projects/euler-cache
+ * https://cfrost.net
  */
 package net.eulerframework.cache.inMemoryCache;
 
@@ -48,7 +48,7 @@ protected CacheTimerObjectCache(CacheTimer<DATA_T> cahceTimer) {
     }
 
     @Override
-    public boolean isTimeout(DataStore<DATA_T> storedData) {
+    public boolean isExpired(DataStore<DATA_T> storedData) {
         if(storedData == null) {
             return true;
         }

diff --git a/src/main/java/net/eulerframework/cache/inMemoryCache/DataNotFoundException.java b/src/main/java/net/eulerframework/cache/inMemoryCache/DataNotFoundException.java
@@ -0,0 +1,9 @@
+package net.eulerframework.cache.inMemoryCache;
+
+@SuppressWarnings("serial")
+public class DataNotFoundException extends Exception {
+
+    public DataNotFoundException(){
+        super("The data does not exist or has expired.");
+    }
+}
diff --git a/src/main/java/net/eulerframework/cache/inMemoryCache/DefaultObjectCache.java b/src/main/java/net/eulerframework/cache/inMemoryCache/DefaultObjectCache.java
@@ -24,16 +24,18 @@
  * For more information, please visit the following website
  *
  * https://eulerproject.io
- * https://github.com/euler-projects/euler-framework
- * http://cfrost.net
+ * https://github.com/euler-projects/euler-cache
+ * https://cfrost.net
  */
 package net.eulerframework.cache.inMemoryCache;
 
 import java.util.Date;
 
 /**
- * 预先指定数据生命周期的对象缓存<br>
- * 如果把生命周期指定为<code>Long.MAX_VALUE</code>表示缓存永不过期
+ * 预先指定数据生命周期的对象缓存
+ * 
+ * <p>如果把生命周期指定为{@link Long#MAX_VALUE}表示缓存永不过期</p>
+ * 
  * Created by cFrost on 16/10/17.
  */
 public class DefaultObjectCache<KEY_T, DATA_T> extends AbstractObjectCache<KEY_T, DATA_T> {
@@ -52,7 +54,7 @@ protected DefaultObjectCache(long dataLife) {
     }
 
     @Override
-    public boolean isTimeout(DataStore<DATA_T> storedData) {
+    public boolean isExpired(DataStore<DATA_T> storedData) {
         //指定为Long.MAX_VALUE表示数据永不过期
         if(this.dataLife == Long.MAX_VALUE ) 
             return false;

diff --git a/src/main/java/net/eulerframework/cache/inMemoryCache/ObjectCachePool.java b/src/main/java/net/eulerframework/cache/inMemoryCache/ObjectCachePool.java
@@ -24,8 +24,8 @@
  * For more information, please visit the following website
  *
  * https://eulerproject.io
- * https://github.com/euler-projects/euler-framework
- * http://cfrost.net
+ * https://github.com/euler-projects/euler-cache
+ * https://cfrost.net
  */
 package net.eulerframework.cache.inMemoryCache;
 
@@ -64,7 +64,7 @@ public static void add(AbstractObjectCache<?, ?> cache) {
     }
 
     /**
-     * 见一个对象缓存从缓存池移除
+     * 将一个对象缓存从缓存池移除
      * 
      * @param cache
      */

diff --git a/src/main/java/net/eulerframework/cache/inMemoryCache/custom/FuzzyObjectCache.java b/src/main/java/net/eulerframework/cache/inMemoryCache/custom/FuzzyObjectCache.java
@@ -24,8 +24,8 @@
  * For more information, please visit the following website
  * 
  * https://eulerproject.io
- * https://github.com/euler-projects/euler-framework
- * http://cfrost.net
+ * https://github.com/euler-projects/euler-cache
+ * https://cfrost.net
  */
 package net.eulerframework.cache.inMemoryCache.custom;
 
@@ -37,6 +37,7 @@
 import java.util.Map.Entry;
 import java.util.Set;
 
+import net.eulerframework.cache.inMemoryCache.DataNotFoundException;
 import net.eulerframework.cache.inMemoryCache.DefaultObjectCache;
 
 /**
@@ -88,8 +89,10 @@ public List<DATA_T> getFuzzy(String key){
     public List<DATA_T> getAll(Set<String> keySet) {
         List<DATA_T> result = new ArrayList<>();
         for(String key : keySet) {
-            DATA_T data = super.get(key);
-            if(data == null){
+            DATA_T data;
+            try {
+                data = super.get(key);
+            } catch (DataNotFoundException e) {
                 return null;
             }
             result.add(data);