001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2009 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: ResourceName.java,v 1.1 2009/11/24 21:42:35 madan_ranganath Exp $
026 *
027 */
028
029package com.sun.identity.shared.whitelist;
030
031import java.net.MalformedURLException;
032import java.util.Map;
033import java.util.Set;
034
035/**
036 * The interface <code>ResourceName</code> provides
037 * methods to determine the hierarchy of resource names.
038 * It provides methods to compare resources, get sub resources etc.
039 * Also it provides an interface to determine the service
040 * type to which it be used. Service developers could
041 * provide an implementation of this interface that will
042 * determine its hierarchy during policy evaluation and
043 * also its display in the GUI. A class that implements
044 * this interface must have a empty constructor.
045 * @supported.all.api
046 */
047public interface ResourceName {
048
049    /**
050     * Returns the service type names for which the resource name
051     * object can be used.
052     *
053     * @return service type names for which the resource
054     * comparator can be used
055     */
056    public Set getServiceTypeNames();
057
058    /**
059     * Initializes the resource name with configuration information,
060     * usually set by the administrators
061     *
062     * @param configParams configuration parameters as a map.
063     * The keys of the map are the configuration parameters. 
064     * Each key is corresponding to one <code>String</code> value
065     * which specifies the configuration parameter value.
066     */
067    public void initialize(Map configParams);
068
069    /**
070     * Compares two resources.
071     *
072     * @param origRes name of the resource which will be compared
073     * @param compRes name of the resource which will be compared with
074     * @param wildcardCompare flag for wildcard comparison
075     *
076     * @return returns <code>ResourceMatch</code> that
077     * specifies if the resources are exact match, or
078     * otherwise.
079     * <ul>
080     * <li><code>ResourceMatch.NO_MATCH</code> means two resources do not match
081     * <li><code>ResourceMatch.EXACT_MATCH</code> means two resources match
082     * <li><code>ResourceMatch.SUB_RESOURCE_MATCH</code> means
083     *     <code>compRes</code> is the sub resource of the <code>origRes</code>
084     * <li><code>ResourceMatch.SUPER_RESOURCE_MATCH</code> means
085     *     <code>compRes</code> is the super resource of the
086     *     <code>origRes</code>
087     * <li><code>ResourceMatch.WILDCARD_MATCH</code> means two resources match
088     *     with respect to the wildcard
089     * </ul>
090     */
091    public ResourceMatch compare(
092        String origRes, String compRes, boolean wildcardCompare);
093    
094    /**
095     * Appends sub-resource to super-resource.
096     *
097     * @param superResource name of the super-resource to be appended to.
098     * @param subResource name of the sub-resource to be appended.
099     *
100     * @return returns the combination resource.
101     */
102    public String append(String superResource, String subResource);
103
104    /**
105     * Gets sub-resource from an original resource minus
106     * a super resource. This is the complementary method of
107     * append().
108     *
109     * @param res name of the original resource consisting of
110     * the second parameter <code>superRes</code> and the returned value
111     * @param superRes name of the super-resource which the first
112     * parameter begins with.
113     *
114     * @return returns the sub-resource which the first parameter
115     * ends with. If the first parameter does not begin with the
116     * the first parameter, then the return value is null.
117     */
118    public String getSubResource(String res, String superRes);
119
120    /**
121     * Gets the canonicalized form of a resource string
122     * 
123     * @param res the resource string to be canonicalized
124     * @return the resource string in its canonicalized form.
125     * @throws MalformedURLException if resource string is invalid
126     */
127    public String canonicalize(String res) throws MalformedURLException;
128
129
130    /******* this method will be removed after the demo ********/
131    /**
132     * Method to split a resource into the smallest necessary
133     * sub resource units
134     *
135     * @param res name of the resource to be split
136     *
137     * @return returns the array of sub-resources, with the first
138     * element being what the original resource begins with, and
139     * the last one being what it ends with
140     */
141    public String[] split(String res);
142
143}