001/*
002 * This file is part of McIDAS-V
003 *
004 * Copyright 2007-2015
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 http://www.gnu.org/licenses.
027 */
028
029package edu.wisc.ssec.mcidasv.servermanager;
030
031
032/**
033 * Represents a source of ADDE data. An ADDE entry may describe a dataset on
034 * remote servers or the user's own machine.
035 */
036public interface AddeEntry {
037
038    /** Represents the possible actions that an ADDE editor can perform. */
039//    @PersistableEnum
040    enum EditorAction {
041        /** Created a new entry; hasn't been verified. */
042        ADDED,
043
044        /** Canceled out of creating or editing an entry. */
045        CANCELLED,
046
047        /** Verified the contents of the editor GUI. */
048        VERIFIED,
049
050        /** Created a new, verified entry. */
051        ADDED_VERIFIED,
052
053        /** Updated an existing entry without verifying changes. */
054        EDITED,
055
056        /** Updated an entry and verified the changes. */
057        EDITED_VERIFIED,
058
059        /** Editor GUI performed some {@literal "invalid"} action. */
060        INVALID;
061    };
062
063    /** Type of chooser this should appear under. */
064    enum EntryType {
065        /** {@link edu.wisc.ssec.mcidasv.chooser.adde.AddeImageChooser} */
066        IMAGE,
067
068        /** {@link edu.wisc.ssec.mcidasv.chooser.adde.AddePointDataChooser} */
069        POINT,
070
071        /** */
072        GRID,
073
074        /** {@link edu.wisc.ssec.mcidasv.chooser.adde.AddeFrontChooser} */
075        TEXT,
076
077        /** */
078        NAV,
079
080        /** {@link edu.wisc.ssec.mcidasv.chooser.adde.AddeRadarChooser} */
081        RADAR,
082
083        /** */
084        UNKNOWN,
085
086        /** */
087        INVALID;
088
089        /**
090         * Attempts to convert a given {@code String} value into a valid 
091         * {@code EntryType}.
092         * 
093         * @param str {@code String} to convert. Should not be {@code null}.
094         * 
095         * @return {@code EntryType} of the value specified in {@code str}.
096         */
097        public static EntryType fromStr(final String str) {
098            return EntryType.valueOf(str);
099        }
100
101        /**
102         * Attempts to convert a given {@code EntryType} into its 
103         * {@code String} representation.
104         * 
105         * @param type {@code EntryType} constant; should not be {@code null}.
106         * 
107         * @return {@code String} representation of {@code type}.
108         */
109        public static String toStr(final EntryType type) {
110            return type.name();
111        }
112    };
113    
114    /** Sort of a {@literal "misc"} status field... */
115    enum EntryValidity {
116        /** Entry has been verified by connecting to the server. */
117        VERIFIED,
118
119        /** Unknown whether or not this entry actually works. */
120        UNVERIFIED,
121
122        /** Entry is being checked for validity. */
123        VALIDATING,
124
125        /** 
126         * User has elected to remove this entry. This is an unfortunate 
127         * {@literal "special case"}, as we can't simply remove these entries
128         * from a list! Say the user import entries from a remote MCTABLE file
129         * and later deleted some of the imported entries. Fine, good! But 
130         * what should happen if the user hears that new servers have been
131         * added to that same MCTABLE file? The entries that the user has 
132         * deleted <i>locally</i> should not reappear, right? 
133         */
134        DELETED,
135
136        /** Entry is invalid in some way. */
137        INVALID;
138
139        public static EntryValidity fromStr(final String str) {
140            return EntryValidity.valueOf(str);
141        }
142        public static String toStr(final EntryValidity validity) {
143            return validity.name();
144        }
145    };
146
147    /** Where did this entry come from? */
148    enum EntrySource {
149        /** Entry originated from McIDAS-V. */
150        SYSTEM, 
151
152        /** Entry was imported from a MCTABLE file. */
153        MCTABLE, 
154
155        /** Entry was added by the user.*/
156        USER,
157
158        /**
159         * Represents an {@literal "invalid"} {@code EntrySource}. Useful for
160         * invalid entry objects ({@link RemoteAddeEntry#INVALID_ENTRY} and 
161         * {@link LocalAddeEntry#INVALID_ENTRY}).
162         */
163        INVALID;
164        
165        public static EntrySource fromStr(final String str) {
166            return EntrySource.valueOf(str);
167        }
168        public static String toStr(final EntrySource source) {
169            return source.name();
170        }
171    };
172
173    /** 
174     * Has the user elected to disable this entry from appearing in its 
175     * relevant chooser? 
176     */
177    enum EntryStatus {
178        /** Entry is valid and toggled on. */
179        ENABLED,
180
181        /** Entry is valid and toggled off. */
182        DISABLED,
183
184        /** Something is wrong with this entry. */
185        INVALID;
186
187        public static EntryStatus fromStr(final String str) {
188            return EntryStatus.valueOf(str);
189        }
190
191        public static String toStr(final EntryType type) {
192            return type.name();
193        }
194    };
195
196    /** Represents the {@literal "no accounting"} entries. */
197    AddeAccount DEFAULT_ACCOUNT = new AddeAccount("idv", "0");
198
199    /**
200     * Address of the server associated with the current entry. 
201     * {@link LocalAddeEntry}s will return {@code localhost}.
202     */
203    String getAddress();
204
205    /**
206     * Dataset/group located on the server.
207     */
208    String getGroup();
209
210    // TODO(jon): what part of a resolv.srv does this represent?
211    /**
212     * Name associated with this entry. 
213     * 
214     * @return Name associated with this entry.
215     */
216    String getName();
217
218    /**
219     * Accounting information associated with the current entry. If the server
220     * does not require accounting information, this method returns 
221     * {@link #DEFAULT_ACCOUNT}.
222     * 
223     * @return ADDE account object.
224     */
225    AddeAccount getAccount();
226
227    /**
228     * Type of chooser this entry should appear under.
229     * 
230     * @return The {@literal "type"} of data associated with this entry.
231     */
232    EntryType getEntryType();
233
234    /**
235     * Does this entry represent a {@literal "valid"} ADDE server.
236     * 
237     * @return Whether or not this entry has been validated.
238     */
239    EntryValidity getEntryValidity();
240
241    /**
242     * Source that specified this entry. For example; allows you to 
243     * distinguish {@literal "system"} entries (which cannot be removed, only 
244     * disabled) from entries created by the user (full control).
245     */
246    EntrySource getEntrySource();
247
248    /**
249     * GUI status of the entry. Differs from {@link EntryValidity} in that 
250     * {@code EntryStatus} controls this entry showing up in a chooser and has
251     * nothing to do with whether or not the entry is a valid ADDE server.
252     */
253    EntryStatus getEntryStatus();
254
255    /**
256     * Handy {@code String} representation of this ADDE entry. Currently looks
257     * like {@code ADDRESS/GROUP}, but this is subject to change.
258     */
259    String getEntryText();
260
261    // TODO(jon): should this be removed? this makes the entries mutable!
262    void setEntryStatus(final EntryStatus newStatus);
263
264    // TODO(jon): integrate with parameter sets one fine day?
265    String getEntryAlias();
266
267    // TODO(jon): should this be removed? this makes the entries mutable!
268    void setEntryAlias(final String newAlias);
269
270    /** */
271    boolean isEntryTemporary();
272
273    /**
274     * Currently used as a identifier for convenient storage by the server 
275     * manager.
276     */
277    String asStringId();
278
279    /**
280     * String representation of this entry.
281     */
282    String toString();
283}