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 }