001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.xbean.kernel;
018    
019    /**
020     * The immutable unique name of a service.  A proper implementation of ServiceName must have a correct implementation of
021     * equals and hashCode.  A ServiceName should have one constructor that takes a single String and the toString method
022     * should return a String that can be used in the String constructor.  This means the following code should work:
023     * <p><blockquote><pre>
024     * Constructor constructor = serviceName.getClass().getConstructor(new Class[] {String.class});
025     * ServiceName name = constructor.newInstance(new Object[] {serviceName.toString()});
026     * </pre></blockquote>
027     *
028     * @author Dain Sundstrom
029     * @version $Id$
030     * @since 2.0
031     */
032    public interface ServiceName {
033        /**
034         * A service name must properly implement hashCode.  For example,
035         * <p><blockquote><pre>
036         * public int hashCode() {
037         *     int result = 17;
038         *     result = 37 * result + integer;
039         *     result = 37 * result + (object == null ? 0 : object.hashCode());
040         *     return result;
041         * }
042         * </pre></blockquote>
043         *
044         * @return the hash code
045         */
046        int hashCode();
047    
048        /**
049         * A service name must property implement equals.  For example,
050         * <p><blockquote><pre>
051         * public boolean equals(Object obj) {
052         *     if (!(obj instanceof MyServiceName)) {
053         *         return false;
054         *     }
055         *     MyServiceName name = (MyServiceName) obj;
056         *     return integer == name.integer &&
057         *             (object == null ? name.object == null : object.equals(name.object));
058         * }
059         * </pre></blockquote>
060         *
061         * @param object some object
062         * @return true if the object is equivalent to this service name; false otherwise
063         */
064        boolean equals(Object object);
065    
066        /**
067         * A service name should return a string from toString that can be used in a String constructor.
068         *
069         * @return the connonical form of this name
070         */
071        String toString();
072    }