Source code

001/*
002 * This file is part of McIDAS-V
003 *
004 * Copyright 2007-2024
005 * Space Science and Engineering Center (SSEC)
006 * University of Wisconsin - Madison
007 * 1225 W. Dayton Street, Madison, WI 53706, USA
008 * https://www.ssec.wisc.edu/mcidas/
009 * 
010 * All Rights Reserved
011 * 
012 * McIDAS-V is built on Unidata's IDV and SSEC's VisAD libraries, and
013 * some McIDAS-V source code is based on IDV and VisAD source code.  
014 * 
015 * McIDAS-V is free software; you can redistribute it and/or modify
016 * it under the terms of the GNU Lesser Public License as published by
017 * the Free Software Foundation; either version 3 of the License, or
018 * (at your option) any later version.
019 * 
020 * McIDAS-V is distributed in the hope that it will be useful,
021 * but WITHOUT ANY WARRANTY; without even the implied warranty of
022 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
023 * GNU Lesser Public License for more details.
024 * 
025 * You should have received a copy of the GNU Lesser Public License
026 * along with this program.  If not, see https://www.gnu.org/licenses/.
027 */
028
029package edu.wisc.ssec.mcidasv.servermanager;
030
031/**
032 * Represents a source of ADDE data. An ADDE entry may describe a dataset on
033 * remote servers or the user's own machine.
034 */
035public interface AddeEntry {
036
037    /** Represents the possible actions that an ADDE editor can perform. */
038    enum EditorAction {
039        /** Created a new entry; hasn't been verified. */
040        ADDED,
041
042        /** Canceled out of creating or editing an entry. */
043        CANCELLED,
044
045        /** Verified the contents of the editor GUI. */
046        VERIFIED,
047
048        /** Created a new, verified entry. */
049        ADDED_VERIFIED,
050
051        /** Updated an existing entry without verifying changes. */
052        EDITED,
053
054        /** Updated an entry and verified the changes. */
055        EDITED_VERIFIED,
056
057        /** Wait for verification and add whatever passed. */
058        VERIFYING_AND_ADDING,
059
060        /** Wait for verification and replace with passing entries. */
061        VERIFYING_AND_EDITING,
062
063        /**
064         * Wait for verification.
065         * Current use is mostly a {@literal "no-op"}.
066         */
067        VERIFYING,
068
069        /** Editor GUI performed some {@literal "invalid"} action. */
070        INVALID
071    }
072
073    /** Type of chooser this should appear under. */
074    enum EntryType {
075        /** {@link edu.wisc.ssec.mcidasv.chooser.adde.AddeImageChooser} */
076        IMAGE,
077
078        /** {@link edu.wisc.ssec.mcidasv.chooser.adde.AddePointDataChooser} */
079        POINT,
080
081        /** */
082        GRID,
083
084        /** {@link edu.wisc.ssec.mcidasv.chooser.adde.AddeFrontChooser} */
085        TEXT,
086
087        /** */
088        NAV,
089
090        /** {@link edu.wisc.ssec.mcidasv.chooser.adde.AddeRadarChooser} */
091        RADAR,
092
093        /** */
094        UNKNOWN,
095
096        /** */
097        INVALID;
098
099        /**
100         * Attempts to convert a given {@code String} value into a valid 
101         * {@code EntryType}.
102         * 
103         * @param str {@code String} to convert. Should not be {@code null}.
104         * 
105         * @return {@code EntryType} of the value specified in {@code str}.
106         */
107        public static EntryType fromStr(final String str) {
108            return EntryType.valueOf(str);
109        }
110
111        /**
112         * Attempts to convert a given {@code EntryType} into its 
113         * {@code String} representation.
114         * 
115         * @param type {@code EntryType} constant; should not be {@code null}.
116         * 
117         * @return {@code String} representation of {@code type}.
118         */
119        public static String toStr(final EntryType type) {
120            return type.name();
121        }
122    }
123    
124    /** Sort of a {@literal "misc"} status field... */
125    enum EntryValidity {
126        /** Entry has been verified by connecting to the server. */
127        VERIFIED,
128
129        /** Unknown whether or not this entry actually works. */
130        UNVERIFIED,
131
132        /** Entry is being checked for validity. */
133        VALIDATING,
134
135        /** 
136         * User has elected to remove this entry. This is an unfortunate 
137         * {@literal "special case"}, as we can't simply remove these entries
138         * from a list! Say the user import entries from a remote MCTABLE file
139         * and later deleted some of the imported entries. Fine, good! But 
140         * what should happen if the user hears that new servers have been
141         * added to that same MCTABLE file? The entries that the user has 
142         * deleted <i>locally</i> should not reappear, right? 
143         */
144        DELETED,
145
146        /** Entry is invalid in some way. */
147        INVALID;
148
149        public static EntryValidity fromStr(final String str) {
150            return EntryValidity.valueOf(str);
151        }
152        public static String toStr(final EntryValidity validity) {
153            return validity.name();
154        }
155    }
156
157    /** Where did this entry come from? */
158    enum EntrySource {
159        /** Entry originated from McIDAS-V. */
160        SYSTEM, 
161
162        /** Entry was imported from a MCTABLE file. */
163        MCTABLE, 
164
165        /** Entry was added by the user.*/
166        USER,
167
168        /**
169         * Represents an {@literal "invalid"} {@code EntrySource}. Useful for
170         * invalid entry objects ({@link RemoteAddeEntry#INVALID_ENTRY} and 
171         * {@link LocalAddeEntry#INVALID_ENTRY}).
172         */
173        INVALID;
174        
175        public static EntrySource fromStr(final String str) {
176            return EntrySource.valueOf(str);
177        }
178        public static String toStr(final EntrySource source) {
179            return source.name();
180        }
181    }
182
183    /** 
184     * Has the user elected to disable this entry from appearing in its 
185     * relevant chooser? 
186     */
187    enum EntryStatus {
188        /** Entry is valid and toggled on. */
189        ENABLED,
190
191        /** Entry is valid and toggled off. */
192        DISABLED,
193
194        /** Something is wrong with this entry. */
195        INVALID;
196
197        public static EntryStatus fromStr(final String str) {
198            return EntryStatus.valueOf(str);
199        }
200
201        public static String toStr(final EntryType type) {
202            return type.name();
203        }
204    }
205
206    /** Represents the {@literal "no accounting"} entries. */
207    AddeAccount DEFAULT_ACCOUNT = new AddeAccount("idv", "0");
208
209    /**
210     * Address of the server associated with the current entry. 
211     * {@link LocalAddeEntry LocalAddeEntries} will return {@code localhost}.
212     *
213     * @return Server address.
214     */
215    String getAddress();
216
217    /**
218     * Dataset/group located on the server.
219     *
220     * @return ADDE group.
221     */
222    String getGroup();
223
224    // TODO(jon): what part of a resolv.srv does this represent?
225    /**
226     * Name associated with this entry. 
227     * 
228     * @return Name associated with this entry.
229     */
230    String getName();
231
232    /**
233     * Accounting information associated with the current entry. If the server
234     * does not require accounting information, this method returns 
235     * {@link #DEFAULT_ACCOUNT}.
236     * 
237     * @return ADDE account object.
238     */
239    AddeAccount getAccount();
240
241    /**
242     * Type of chooser this entry should appear under.
243     * 
244     * @return The {@literal "type"} of data associated with this entry.
245     */
246    EntryType getEntryType();
247
248    /**
249     * Does this entry represent a {@literal "valid"} ADDE server.
250     * 
251     * @return Whether or not this entry has been validated.
252     */
253    EntryValidity getEntryValidity();
254
255    /**
256     * Source that specified this entry. For example; allows you to 
257     * distinguish {@literal "system"} entries (which cannot be removed, only 
258     * disabled) from entries created by the user (full control).
259     *
260     * @return Source of this entry.
261     */
262    EntrySource getEntrySource();
263
264    /**
265     * GUI status of the entry. Differs from {@link EntryValidity} in that 
266     * {@code EntryStatus} controls this entry showing up in a chooser and has
267     * nothing to do with whether or not the entry is a valid ADDE server.
268     *
269     * @return Status of this entry.
270     */
271    EntryStatus getEntryStatus();
272
273    /**
274     * Handy {@code String} representation of this ADDE entry. Currently looks
275     * like {@code ADDRESS/GROUP}, but this is subject to change.
276     *
277     * @return Entry as a {@code String}.
278     */
279    String getEntryText();
280
281    // TODO(jon): should this be removed? this makes the entries mutable!
282    void setEntryStatus(final EntryStatus newStatus);
283
284    // TODO(jon): integrate with parameter sets one fine day?
285    String getEntryAlias();
286
287    // TODO(jon): should this be removed? this makes the entries mutable!
288    void setEntryAlias(final String newAlias);
289
290    /**
291     * Determine whether or not this entry will be saved between application
292     * sessions.
293     *
294     * @return Whether or not this entry is saved for subsequent sessions.
295     */
296    boolean isEntryTemporary();
297
298    /**
299     * Currently used as a identifier for convenient storage by the server 
300     * manager.
301     *
302     * @return Identifier for this entry.
303     */
304    String asStringId();
305
306    /**
307     * String representation of this entry.
308     *
309     * <p>Output will typically contain internal details and as such will differ
310     * from {@link #getEntryText()}.</p>
311     *
312     * @return Entry as a {@code String}.
313     */
314    String toString();
315}