001    /*
002     * file Provider.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM
006     *
007     * (c) Copyright IBM Corporation 2004, 2008.  All Rights Reserved. 
008     * Note to U.S. Government Users Restricted Rights:  Use, duplication or  
009     * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
010     */
011    package javax.wvcm;
012    
013    import java.util.Map;
014    
015    import javax.wvcm.ProviderFactory.Callback;
016    import javax.wvcm.WvcmException.ReasonCode;
017    
018    /**
019     * A WVCM provider.
020     *
021     * A WVCM provider is a factory for creating new locations, resource lists
022     * and the generic Resource proxy. 
023     * 
024     * @since 1.0
025     */
026    public interface Provider {
027            
028        /**
029         * Initialize the provider with the specified map and callback.
030         * This is used to initialize a provider that was created with the zero-argument constructor.
031         * @param initArgs arguments used to customize the behavior of the provider.
032         * @param callback allows the provider to call back to the client for additional information.
033         * @throws WvcmException if the initArgs are invalid.
034         */
035            public void initialize(Map<String, String> initArgs, Callback callback) throws WvcmException;
036        
037        /**
038         * Return the initialization arguments for this provider.
039         * @return the initialization arguments for this provider.
040         */
041        public Map<String, String> initArgs();
042            
043        /**
044         * Return the initialization arguments for this provider.
045         * @return the initialization arguments for this provider.
046         */
047        public Callback callback();
048        
049        /**
050         * A valid folder location for this provider.
051         * 
052         * @return a valid folder location for this provider.
053         * If this provider supports access to multiple repositories,
054         * each sibling (i.e. resource with the same parent) of this folder
055         * will commonly identify a repository.
056         */
057        public Location rootLocation();
058            
059        /**
060         * A location used in a property of a resource to indicate that this location should 
061         * be interpreted relative to the folder that contains the resource.
062         */
063        public Location relativeRootLocation();
064        
065        /**
066         * Location factory for this Provider.
067         * 
068         * @param string the format of the location string is specific to the Provider,
069         * and to the repository that stores the persistent resource.
070         * A URL, a UNC filename, and an NFS filename
071         * are examples of possible formats for a location string.
072         * 
073         * @return a Location whose string value is the specified String.
074         * @throws WvcmException ReasonCode:
075         * <li>{@link ReasonCode#ILLEGAL_LOCATION_SYNTAX}:
076         *  String is not a valid location.
077         */
078        public Location location(String string) throws WvcmException;
079    
080        /**
081         * Construct a proxy of class T for the given location.
082         * 
083         * @param type the type of the proxy.
084         * @param loc the location of the resource.
085         * @return a new proxy for a resource at this Location.
086         */
087        public <T extends Resource> T buildProxy(Class<T> type, Location loc)
088        throws WvcmException; 
089        
090        /**
091         * Construct a resource proxy for the given location.
092         * 
093         * @param loc the location of the resource.
094         * @return a new proxy for a resource at this Location.
095         */
096        public Resource resource(Location loc);
097    
098        /**
099         * Construct a folder proxy for the given location.
100         * 
101         * @param loc the location of the folder.
102         * @return a new proxy for a folder at this Location.
103         */
104        public Folder folder(Location loc);
105    
106        /**
107         * Construct a new {@link ResourceList}.
108         * 
109         * @param resources An array of resource proxies from which the list
110         * is to be initialized. 
111         * 
112         * @return a ResourceList initialized by the specified resources.
113         */
114        public <T extends Resource> ResourceList<T> resourceList(T... resources);
115        
116    }