001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.net;
019
020import java.util.List;
021
022import org.apache.hadoop.classification.InterfaceAudience;
023import org.apache.hadoop.classification.InterfaceStability;
024
025/**
026 * An interface that must be implemented to allow pluggable
027 * DNS-name/IP-address to RackID resolvers.
028 *
029 */
030@InterfaceAudience.Public
031@InterfaceStability.Evolving
032public interface DNSToSwitchMapping {
033  /**
034   * Resolves a list of DNS-names/IP-addresses and returns back a list of
035   * switch information (network paths). One-to-one correspondence must be 
036   * maintained between the elements in the lists. 
037   * Consider an element in the argument list - x.y.com. The switch information
038   * that is returned must be a network path of the form /foo/rack, 
039   * where / is the root, and 'foo' is the switch where 'rack' is connected.
040   * Note the hostname/ip-address is not part of the returned path.
041   * The network topology of the cluster would determine the number of
042   * components in the network path.
043   * <p/>
044   *
045   * If a name cannot be resolved to a rack, the implementation
046   * should return {@link NetworkTopology#DEFAULT_RACK}. This
047   * is what the bundled implementations do, though it is not a formal requirement
048   *
049   * @param names the list of hosts to resolve (can be empty)
050   * @return list of resolved network paths.
051   * If <i>names</i> is empty, the returned list is also empty
052   */
053  public List<String> resolve(List<String> names);
054
055  /**
056   * Reload all of the cached mappings.
057   *
058   * If there is a cache, this method will clear it, so that future accesses
059   * will get a chance to see the new data.
060   */
061  public void reloadCachedMappings();
062  
063  /**
064   * Reload cached mappings on specific nodes.
065   *
066   * If there is a cache on these nodes, this method will clear it, so that 
067   * future accesses will see updated data.
068   */
069  public void reloadCachedMappings(List<String> names);
070}