001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019package org.apache.reef.io; 020 021import org.apache.reef.annotations.Unstable; 022 023import java.util.Map; 024import java.util.Set; 025 026/** 027 * A Map interface for data that can be swapped out to other processes, managed 028 * by native code, paged to disk, stored remotely, etc... 029 * 030 * @param <T> the entry type of the map 031 */ 032@Unstable 033public interface ExternalMap<T> { 034 035 /** 036 * @param key 037 * @return true, if an entry with the given key exists 038 */ 039 boolean containsKey(final CharSequence key); 040 041 /** 042 * Element access. 043 * 044 * @param key 045 * @return the object stored under key nor null if no such object exists 046 */ 047 T get(final CharSequence key); 048 049 /** 050 * Put a record into the map. 051 * 052 * @param key 053 * @param value 054 * @return the previous value associated with key, or null if there was no 055 * mapping for key. (A null return can also indicate that the map previously 056 * associated null with key, if the implementation supports null values.) 057 */ 058 T put(final CharSequence key, final T value); 059 060 /** 061 * Removes the mapping for a key from this map if it is present (optional 062 * operation). More formally, if this map contains a mapping from key k to 063 * value v such that (key==null ? k==null : key.equals(k)), that mapping is 064 * removed. (The map can contain at most one such mapping.) Returns the 065 * value to which this map previously associated the key, or null if the map 066 * contained no mapping for the key. 067 * <p> 068 * If this map permits null values, then a return value of null does not 069 * necessarily indicate that the map contained no mapping for the key; it's 070 * also possible that the map explicitly mapped the key to null. 071 * <p> 072 * The map will not contain a mapping for the specified key once the call 073 * returns. 074 * 075 * @param key key whose mapping is to be removed from the map 076 * @return the previous value associated with key, or null if there was no 077 * mapping for key. 078 */ 079 T remove(final CharSequence key); 080 081 /** 082 * Copies all of the mappings from the specified map to this map (optional 083 * operation). The effect of this call is equivalent to that of calling 084 * put(k, v) on this map once for each mapping from key k to value v in the 085 * specified map. The behavior of this operation is undefined if the 086 * specified map is modified while the operation is in progress. 087 * 088 * @param m 089 */ 090 void putAll(final Map<? extends CharSequence, ? extends T> m); 091 092 Iterable<Map.Entry<CharSequence, T>> getAll(Set<? extends CharSequence> keys); 093}