001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/memory/tags/sakai_2-4-1/memory-api/api/src/java/org/sakaiproject/memory/api/MemoryService.java $
003: * $Id: MemoryService.java 7220 2006-03-29 15:23:17Z ggolden@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.memory.api;
021:
022: /**
023: * <p>
024: * MemoryService is the interface for the Sakai Memory service.
025: * </p>
026: * <p>
027: * This tracks memory users (cachers), runs a periodic garbage collection to keep memory available, and can be asked to report memory usage.
028: * </p>
029: */
030: public interface MemoryService {
031: /**
032: * Report the amount of available memory.
033: *
034: * @return the amount of available memory.
035: */
036: long getAvailableMemory();
037:
038: /**
039: * Cause less memory to be used by clearing any optional caches.
040: *
041: * @exception PermissionException
042: * if the current user does not have permission to do this.
043: */
044: void resetCachers() throws MemoryPermissionException;
045:
046: /**
047: * Register as a cache user
048: */
049: void registerCacher(Cacher cacher);
050:
051: /**
052: * Unregister as a cache user
053: */
054: void unregisterCacher(Cacher cacher);
055:
056: /**
057: * Construct a Cache. Attempts to keep complete on Event notification by calling the refresher.
058: *
059: * @param refresher
060: * The object that will handle refreshing of event notified modified or added entries.
061: * @param pattern
062: * The "startsWith()" string for all resources that may be in this cache - if null, don't watch events for updates.
063: */
064: Cache newCache(CacheRefresher refresher, String pattern);
065:
066: /**
067: * Construct a special Cache that uses hard references. Attempts to keep complete on Event notification by calling the refresher.
068: *
069: * @param refresher
070: * The object that will handle refreshing of event notified modified or added entries.
071: * @param pattern
072: * The "startsWith()" string for all resources that may be in this cache - if null, don't watch events for updates.
073: */
074: Cache newHardCache(CacheRefresher refresher, String pattern);
075:
076: /**
077: * Construct a Cache. Automatic refresh handling if refresher is not null.
078: *
079: * @param refresher
080: * The object that will handle refreshing of expired entries.
081: * @param sleep
082: * The number of seconds to sleep between expiration checks.
083: */
084: Cache newCache(CacheRefresher refresher, long sleep);
085:
086: /**
087: * Construct a Cache. Automatic refresh handling if refresher is not null.
088: *
089: * @param refresher
090: * The object that will handle refreshing of expired entries.
091: * @param sleep
092: * The number of seconds to sleep between expiration checks.
093: */
094: Cache newHardCache(CacheRefresher refresher, long sleep);
095:
096: /**
097: * Construct a Cache. No automatic refresh: expire only, from time and events.
098: *
099: * @param sleep
100: * The number of seconds to sleep between expiration checks.
101: * @param pattern
102: * The "startsWith()" string for all resources that may be in this cache - if null, don't watch events for expiration.
103: */
104: Cache newHardCache(long sleep, String pattern);
105:
106: /**
107: * Construct a Cache. No automatic refresh handling.
108: */
109: Cache newCache();
110:
111: /**
112: * Construct a Cache. No automatic refresh handling.
113: */
114: Cache newHardCache();
115:
116: /**
117: * Construct a multi-ref Cache. No automatic refresh: expire only, from time and events.
118: *
119: * @param sleep
120: * The number of seconds to sleep between expiration checks.
121: */
122: MultiRefCache newMultiRefCache(long sleep);
123:
124: /**
125: * Get a status report of memory users.
126: *
127: * @return A status report of memory users.
128: */
129: String getStatus();
130: }
|