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 */
011package javax.wvcm;
012
013import java.util.Map;
014
015import javax.wvcm.ProviderFactory.Callback;
016import 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 */
026public 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}