01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * http://www.apache.org/licenses/LICENSE-2.0
10: *
11: * Unless required by applicable law or agreed to in writing, software
12: * distributed under the License is distributed on an "AS IS" BASIS,
13: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14: * See the License for the specific language governing permissions and
15: * limitations under the License.
16: */
17: package org.apache.cocoon.components.resolver;
18:
19: import org.apache.avalon.framework.component.Component;
20: import org.xml.sax.EntityResolver;
21: import org.xml.sax.InputSource;
22: import org.xml.sax.SAXException;
23: import java.io.IOException;
24:
25: /**
26: * A component that uses catalogs for resolving entities.
27: * @deprecated Use the Avalon Excalibur EntityResolver instead
28: *
29: * @author <a href="mailto:dims@yahoo.com">Davanum Srinivas</a>
30: * @author <a href="mailto:crossley@apache.org">David Crossley</a>
31: * @version CVS $Id: Resolver.java 433543 2006-08-22 06:22:54Z crossley $
32: */
33: public interface Resolver extends Component, EntityResolver {
34:
35: String ROLE = "org.apache.cocoon.components.resolver.Resolver";
36:
37: /**
38: * Allow the application to resolve external entities.
39: *
40: * <p>The Parser will call this method before opening any external
41: * entity except the top-level document entity (including the
42: * external DTD subset, external entities referenced within the
43: * DTD, and external entities referenced within the document
44: * element): the application may request that the parser resolve
45: * the entity itself, that it use an alternative URI, or that it
46: * use an entirely different input source.</p>
47: *
48: * <p>Application writers can use this method to redirect external
49: * system identifiers to secure and/or local URIs, to look up
50: * public identifiers in a catalogue, or to read an entity from a
51: * database or other input source (including, for example, a dialog
52: * box).</p>
53: *
54: * <p>If the system identifier is a URL, the SAX parser must
55: * resolve it fully before reporting it to the application.</p>
56: *
57: * @param publicId The public identifier of the external entity
58: * being referenced, or null if none was supplied.
59: * @param systemId The system identifier of the external entity
60: * being referenced.
61: * @return An InputSource object describing the new input source,
62: * or null to request that the parser open a regular
63: * URI connection to the system identifier.
64: * @exception org.xml.sax.SAXException Any SAX exception, possibly
65: * wrapping another exception.
66: * @exception java.io.IOException A Java-specific IO exception,
67: * possibly the result of creating a new InputStream
68: * or Reader for the InputSource.
69: * @see org.xml.sax.InputSource
70: */
71: InputSource resolveEntity(String publicId, String systemId)
72: throws SAXException, IOException;
73: }
|