001/*
002 * jPOS Project [http://jpos.org]
003 * Copyright (C) 2000-2026 jPOS Software SRL
004 *
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Affero General Public License as
007 * published by the Free Software Foundation, either version 3 of the
008 * License, or (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013 * GNU Affero General Public License for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License
016 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
017 */
018
019package org.jpos.space;
020
021
022/**
023 * <p><b>Space</b> uses concepts described in the Linda Coordination Language 
024 * that eases the implementation of other jPOS components (such as 
025 * Channels, Muxes, etc.), but it is not by any means an attempt to provide
026 * a full implementation.</p>
027 *
028 * <p>jPOS's Space is basically a Map where each entry is a LinkedList 
029 * of values that can be used as a BlockingQueue</p>
030 *
031 * <p>One can place entries on a queue by calling Space.out, take them
032 * by calling Space.in and read (without taking) by calling Space.rd</p>
033 *
034 * @author Alejandro Revilla
035 * @version $Revision$ $Date$
036 * @since 2.0
037 * @see TSpace
038 * @see SpaceError
039 * @see <a href="http://www.cs.yale.edu/Linda/linda-lang.html">The Linda Coordination Language</a>
040
041 * @param <K> the key type
042 * @param <V> the value type
043 */
044
045public interface Space<K,V> extends AutoCloseable {
046    /**
047     * Write a new entry into the Space
048     * @param key Entry's key
049     * @param value Object value
050     */
051    void out(K key, V value);
052
053    /**
054     * Write a new entry into the Space, with an timeout value
055     * @param key Entry's key
056     * @param value Object value
057     * @param timeout timeout value in millis
058     */
059    void out(K key, V value, long timeout);
060
061    /**
062     * Take an entry from the space, waiting forever until one exists.
063     * @param key Entry's key
064     * @return value
065     */
066    V in(K key);
067
068    /**
069     * Read an entry from the space, waiting forever until one exists.
070     * @param key Entry's key
071     * @return value
072     */
073    V rd(K key);
074
075    /**
076     * Take an entry from the space, waiting a limited amount of time
077     * until one exists.
078     * @param key Entry's key
079     * @param timeout millis to wait
080     * @return value or null
081     */
082    V in(K key, long timeout);
083
084
085    /**
086     * Read an entry from the space, waiting a limited amount of time
087     * until one exists.
088     * @param key Entry's key
089     * @param timeout millis to wait
090     * @return value or null
091     */
092    V rd(K key, long timeout);
093
094
095    /**
096     * In probe takes an entry from the space if one exists, 
097     * return null otherwise.
098     * @param key Entry's key
099     * @return value or null
100     */
101    V inp(K key);
102
103
104    /**
105     * Read probe reads an entry from the space if one exists, 
106     * return null otherwise.
107     * @param key Entry's key
108     * @return value or null
109     */
110    V rdp(K key);
111
112    /**
113     * Nrd (not read) waits forever until Key is not present in space.<br/>
114     * Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.
115     * @param key Entry's key
116     */
117    void nrd(K key);
118
119    /**
120     * Nrd (not read) waits up to timeout until Key is not present in space.<br/>
121     * Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.
122     * @param key Entry's key
123     * @param timeout millis to wait
124     * @return value or null
125     */
126    V nrd(K key, long timeout);
127
128    /**
129     * Write a new entry at the head of a queue.
130     * @param key Entry's key
131     * @param value Object value
132     */
133    void push(K key, V value);
134
135    /**
136     * Write a new entry at the head of the queue with a timeout value
137     * @param key Entry's key
138     * @param value Object value
139     * @param timeout timeout value in millis
140     */
141    void push(K key, V value, long timeout);
142
143    /**
144     * Returns true if any of the given keys are present in the space.
145     * @param keys array of keys to check
146     * @return true if one or more keys are available in the space
147     */
148    boolean existAny(K[] keys);
149
150    /**
151     * Returns true if any of the given keys become available within the timeout.
152     * @param keys array of keys to check
153     * @param timeout to wait for any of the entries to become available in millis
154     * @return true if one or more keys are available in the space
155     */
156    boolean existAny(K[] keys, long timeout);
157
158    /**
159     * Write a single entry at the head of the queue discarding the other entries
160     * @param key Entry's key
161     * @param value Object value
162
163     */
164    void put(K key, V value);
165
166    /**
167     * Write a single entry at the head of the queue discarding the other entries, with timeout.
168     * @param key Entry's key
169     * @param value Object value
170     * @param timeout timeout value in millis
171     */
172    void put(K key, V value, long timeout);
173
174    @Override
175    default void close() {}
176}