001package jmri;
002
003import javax.annotation.CheckForNull;
004import javax.annotation.Nonnull;
005
006/**
007 * Interface for obtaining Routes.
008 * <p>
009 * This doesn't have a "new" method, since Routes are separately implemented,
010 * instead of being system-specific.
011 *
012 * <hr>
013 * This file is part of JMRI.
014 * <p>
015 * JMRI is free software; you can redistribute it and/or modify it under the
016 * terms of version 2 of the GNU General Public License as published by the Free
017 * Software Foundation. See the "COPYING" file for a copy of this license.
018 * <p>
019 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
020 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
021 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
022 *
023 * @author Dave Duchamp Copyright (C) 2004
024 */
025public interface RouteManager extends ProvidingManager<Route> {
026
027    // to free resources when no longer used
028    @Override
029    void dispose();
030
031    /**
032     * Provides existing Route by UserName then SystemName if one exists.
033     * Create a new Route if the route does not exist.
034     * @param systemName the system name for the route
035     * @param userName   the user name for the route
036     * @return New or existing Route.
037     * @throws IllegalArgumentException if there is trouble creating a new Route
038     */
039    @Nonnull
040    Route provideRoute(@Nonnull String systemName, @CheckForNull String userName) throws IllegalArgumentException;
041
042    /**
043     * Create a new Route if the route does not exist.
044     * Intended for use with User GUI, to allow the auto generation of 
045     * systemNames, where the user can optionally supply a username.
046     *
047     * @param userName user name for the new route
048     * @return New Route.
049     * @throws IllegalArgumentException if there is trouble creating a new Route
050     */
051    @Nonnull
052    Route newRoute(@Nonnull String userName) throws IllegalArgumentException;
053
054    /**
055     * Locate via user name, then system name if needed.
056     * Does not create a new one if nothing found.
057     *
058     * @param name User name or system name to match
059     * @return null if no match found
060     */
061    @CheckForNull
062    Route getRoute(@Nonnull String name);
063
064    @CheckForNull
065    @Override
066    Route getByUserName(@Nonnull String s);
067
068    @CheckForNull
069    @Override
070    Route getBySystemName(@Nonnull String s);
071
072    /**
073     * Delete Route by removing it from the manager. The Route must first be
074     * deactivated so it stops processing.
075     *
076     * @param r the route to remove
077     */
078    void deleteRoute(@Nonnull Route r);
079
080}