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}