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     */
018    package org.apache.hadoop.net;
019    
020    import java.util.List;
021    
022    import org.apache.hadoop.classification.InterfaceAudience;
023    import 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
032    public 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    }