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}