1/*
2 * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package jdk.internal.jshell.tool;
27
28/**
29 * The required functionality jshell uses for persistent storage.  Implementable
30 * by both Preferences API and Map.
31 */
32interface PersistentStorage {
33
34    /**
35     * Removes all of the preferences (key-value associations) in
36     * preferences.
37     *
38     * @throws IllegalStateException if this operation cannot be completed
39     * because of the state of the system.
40     */
41    void clear();
42
43    /**
44     * Returns all of the keys that have an associated value in
45     * preferences.
46     *
47     * @return an array of the keys that have an associated value in this
48     * preference node.
49     * @throws IllegalStateException if this operation cannot be completed
50     * because of the state of the system.
51     */
52    String[] keys();
53
54    /**
55     * Returns the value associated with the specified key in preferences.
56     *
57     * @param key key whose associated value is to be returned.
58     * @return the value associated with {@code key}, or {@code null} if no
59     * value is associated with {@code key}.
60     * @throws IllegalStateException if this operation cannot be completed
61     * because of the state of the system.
62     * @throws NullPointerException if {@code key} is {@code null}.
63     */
64    String get(String key);
65
66    /**
67     * Associates the specified value with the specified key in this
68     * preference node.
69     *
70     * @param key key with which the specified value is to be associated.
71     * @param value value to be associated with the specified key.
72     * @throws NullPointerException if key or value is {@code null}.
73     * @throws IllegalArgumentException if key or value are too long.
74     * @throws IllegalStateException if this operation cannot be completed
75     * because of the state of the system.
76     */
77    void put(String key, String value);
78
79    /**
80     * Removes the value associated with the specified key in preferences,
81     * if any.
82     *
83     * @param key key whose mapping is to be removed from the preference
84     * node.
85     * @throws NullPointerException if {@code key} is {@code null}.
86     * @throws IllegalStateException if this operation cannot be completed
87     * because of the state of the system.
88     */
89    void remove(String key);
90
91    /**
92     * Forces any changes in the contents of this preferences to be stored.
93     * Once this method returns successfully, it is safe to assume that all
94     * changes have become as permanent as they are going to be.
95     * <p>
96     * Implementations are free to flush changes into the persistent store
97     * at any time. They do not need to wait for this method to be called.
98     *
99     * @throws IllegalStateException if this operation cannot be completed
100     * because of the state of the system.
101     */
102    void flush();
103
104}
105