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
042public interface Space<K,V> extends AutoCloseable {
043    /**
044     * Write a new entry into the Space
045     * @param key Entry's key
046     * @param value Object value
047     */
048    void out(K key, V value);
049
050    /**
051     * Write a new entry into the Space, with an timeout value
052     * @param key Entry's key
053     * @param value Object value
054     * @param timeout timeout value in millis
055     */
056    void out(K key, V value, long timeout);
057
058    /**
059     * Take an entry from the space, waiting forever until one exists.
060     * @param key Entry's key
061     * @return value
062     */
063    V in(K key);
064
065    /**
066     * Read an entry from the space, waiting forever until one exists.
067     * @param key Entry's key
068     * @return value
069     */
070    V rd(K key);
071
072    /**
073     * Take an entry from the space, waiting a limited amount of time
074     * until one exists.
075     * @param key Entry's key
076     * @param timeout millis to wait
077     * @return value or null
078     */
079    V in(K key, long timeout);
080
081
082    /**
083     * Read an entry from the space, waiting a limited amount of time
084     * until one exists.
085     * @param key Entry's key
086     * @param timeout millis to wait
087     * @return value or null
088     */
089    V rd(K key, long timeout);
090
091
092    /**
093     * In probe takes an entry from the space if one exists, 
094     * return null otherwise.
095     * @param key Entry's key
096     * @return value or null
097     */
098    V inp(K key);
099
100
101    /**
102     * Read probe reads an entry from the space if one exists, 
103     * return null otherwise.
104     * @param key Entry's key
105     * @return value or null
106     */
107    V rdp(K key);
108
109    /**
110     * Nrd (not read) waits forever until Key is not present in space.<br/>
111     * Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.
112     * @param key Entry's key
113     */
114    void nrd(K key);
115
116    /**
117     * Nrd (not read) waits up to timeout until Key is not present in space.<br/>
118     * Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.
119     * @param key Entry's key
120     * @param timeout millis to wait
121     * @return value or null
122     */
123    V nrd(K key, long timeout);
124
125    /**
126     * Write a new entry at the head of a queue.
127     * @param key Entry's key
128     * @param value Object value
129     */
130    void push(K key, V value);
131
132    /**
133     * Write a new entry at the head of the queue with a timeout value
134     * @param key Entry's key
135     * @param value Object value
136     * @param timeout timeout value in millis
137     */
138    void push(K key, V value, long timeout);
139
140    /**
141     * @param keys array of keys to check
142     * @return true if one or more keys are available in the space
143     */
144    boolean existAny(K[] keys);
145
146    /**
147     * @param keys array of keys to check
148     * @param timeout to wait for any of the entries to become available in millis
149     * @return true if one or more keys are available in the space
150     */
151    boolean existAny(K[] keys, long timeout);
152
153    /**
154     * Write a single entry at the head of the queue discarding the other entries
155     * @param key Entry's key
156     * @param value Object value
157
158     */
159    void put(K key, V value);
160
161    /**
162     * Write a single entry at the head of the queue discarding the other entries, with timeout.
163     * @param key Entry's key
164     * @param value Object value
165     * @param timeout timeout value in millis
166     */
167    void put(K key, V value, long timeout);
168
169    @Override
170    default void close() {}
171}