KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > modules > xml > retriever > Retriever


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.netbeans.modules.xml.retriever;
21
22 import java.io.File JavaDoc;
23 import java.io.IOException JavaDoc;
24 import java.net.URI JavaDoc;
25 import java.net.URISyntaxException JavaDoc;
26 import java.net.UnknownHostException JavaDoc;
27 import java.util.Map JavaDoc;
28 import org.openide.filesystems.FileObject;
29
30 /**
31  * The Retriever interface supports retrieving the closure of XML documents into
32  * a project.
33  * @author girix
34  * @see The created catalog can be edited programatically by the following interface impl
35  * org.netbeans.modules.xml.retriever.catalog.CatalogWriteModel
36  * To get the impl instance use org.netbeans.modules.xml.retriever.catalog.CatalogWriteModelFactory
37  */
38 public abstract class Retriever {
39     
40     /**
41      * Retrieves an XML resource given the resource's URI. Call getRetrievedResourceExceptionMap() to
42      * get exception messages that occured dring retrieve process.
43      * @param destinationDir A folder inside a NB project (ONLY) to which the
44      * retrieved resource will be copied. All referenced resources will be
45      * copied relative to this directory.
46      * @param relativePathToCatalogFile represents the URI to the catalog file
47      * which should contain the mappings for the retrieved resources. The
48      * path should be relative to the project directory. This file will be
49      * created if it does not exist. Passing null will use the default
50      * catalog file for the project from {@link org.netbeans.modules.xml.retriever.XMLCatalogProvider#getProjectWideCatalog()}
51      * @param resourceToRetrieve URI of the XML resource that will be retrieved
52      * and stored within destinationDir
53      * @return FileObject of the retrieved resource in the local file system
54      */
55     public abstract FileObject retrieveResource(
56             FileObject destinationDir,
57             URI JavaDoc relativePathToCatalogFile,
58             URI JavaDoc resourceToRetrieve)
59             throws UnknownHostException JavaDoc, URISyntaxException JavaDoc, IOException JavaDoc;
60     
61     /**
62      * Retrieves an XML resource given the resource's URI. Call getRetrievedResourceExceptionMap() to
63      * get exception messages that occured dring retrieve process. Calling this
64      * method is equivalent to calling <code> retrieveResource(FileObject, null, URI) </code>
65      *
66      * This method will use #XMLCatalogProvider.getProjectWideCatalog() to store
67      * the mapping between the retrieved URL's and local files.
68      * @param destinationDir A folder inside a NB project (ONLY) to which the retrieved resource will be copied to. All retrieved imported/included resources will be copied relative to this directory.
69      * @param resourceToRetrieve URI of the XML resource that will be retrieved into the project
70      *
71      * @return FileObject of the retrieved resource in the local file system
72      */
73     public abstract FileObject retrieveResource(FileObject destinationDir, URI JavaDoc resourceToRetrieve)
74     throws UnknownHostException JavaDoc, URISyntaxException JavaDoc, IOException JavaDoc;
75     
76     
77     
78     /**
79      * Retrieves an XML resource given the resource's URI. Call getRetrievedResourceExceptionMap() to
80      * get exception messages that occured dring retrieve process. The files
81      * retrieved will be stored in <code>destinationDir</code> and names will
82      * use a uniquifying algorithm. This method will not attempt to preserve
83      * relative references. Relative references will be retrieved and the
84      * referencing files will remain unchanged; thus the catalog may contain
85      * relative references.
86      *
87      * This method will use #XMLCatalogProvider.getProjectWideCatalog() to store
88      * the mapping between the retrieved URL's and local files.
89      * @param destinationDir A folder inside a NB project (ONLY) to which the retrieved resource will be copied to. All retrieved imported/included resources will be copied relative to this directory.
90      * @param resourceToRetrieve URI of the XML resource that will be retrieved into the project
91      *
92      * @return FileObject of the retrieved resource in the local file system
93      */
94     public abstract FileObject retrieveResourceClosureIntoSingleDirectory(
95             FileObject destinationDir, URI JavaDoc resourceToRetrieve)
96             throws UnknownHostException JavaDoc, URISyntaxException JavaDoc, IOException JavaDoc;
97     
98     
99     
100     /**
101      * Returns a global OASIS catalog file that has all the mappings of retrieved entries
102      * in this project. This must be called after retrieveResource is called to get the
103      * most latest entries (along with the old ones that are already in this project).
104      *
105      * The #retrieveResource(FileObject,URI,URI) method should be
106      * used instead of this method to control the catalog file used.
107      */
108     @Deprecated JavaDoc()
109     public abstract File JavaDoc getProjectCatalog();
110     
111     /**
112      * Returns the default implementation of the Retriever.
113      */
114     public static Retriever getDefault(){
115         return new RetrieverImpl();
116     }
117     
118     /**
119      * Returns a map that maps retrieved entries that had exceptions while
120      * retrieving, along with the exceptions.
121      * @return returns a map or null incase if there were no exceptions.
122      */
123     public abstract Map JavaDoc<RetrieveEntry, Exception JavaDoc> getRetrievedResourceExceptionMap();
124     
125     /**
126      * Added this back just to fix build break.
127      * This method will be removed soon. Please make sure not to use this method anymore.
128      * @deprecated Please use {@link retrieveResource(FileObject, URI)} instead
129      */
130     public abstract File JavaDoc retrieveResource(File JavaDoc targetFolder, URI JavaDoc source)
131     throws UnknownHostException JavaDoc, URISyntaxException JavaDoc, IOException JavaDoc;
132     
133     /**
134      * Must be called before calling any retrieveResource* method.
135      * Instruct the retriever NOT to pull down the imported files recursively (closure)
136      * by passing retrieveRecursively = false or true otherwise (true is default)
137      */
138     public abstract void setRecursiveRetrieve(boolean retrieveRecursively);
139     
140     /**
141      * Must be called before calling any retrieveResource* method.
142      * Instruct the retriever NOT to overwrite files with same name
143      * by passing overwriteFiles = false or true otherwise (true is default)
144      */
145     public abstract void setOverwriteFilesWithSameName(boolean overwriteFiles);
146     
147     
148     
149 }
150
Popular Tags