lib/sax/entity_resolver.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # This file is free software, which comes along with NIT. This software is
   4 # distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
   5 # without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
   6 # PARTICULAR PURPOSE. You can modify it is you want, provided this header
   7 # is kept unaltered, and a notification of the changes is added.
   8 # You are allowed to redistribute it and sell it, alone or is a part of
   9 # another product.
  10
  11 # Basic interface for resolving entities.
  12 module sax::entity_resolver
  13
  14 import input_source
  15
  16 # Basic interface for resolving entities.
  17 #
  18 # If a SAX application needs to implement customized handling
  19 # for external entities, it must implement this interface and
  20 # register an instance with the SAX driver using the
  21 # `sax::XMLReader.entity_resolver` property.
  22 #
  23 # The XML reader will then allow the application to intercept any
  24 # external entities (including the external DTD subset and external
  25 # parameter entities, if any) before including them.
  26 #
  27 # Many SAX applications will not need to implement this interface,
  28 # but it will be especially useful for applications that build
  29 # XML documents from databases or other specialised input sources,
  30 # or for applications that use URI types other than URLs.
  31 #
  32 # The application can also use this interface to redirect system
  33 # identifiers to local URIs or to look up replacements in a catalog
  34 # (possibly by using the public identifier).
  35 #
  36 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
  37 #
  38 # SEE: `sax::XMLReader.entity_resolver`
  39 #
  40 # SEE: `sax::InputSource`
  41 abstract class EntityResolver
  42
  43         # Allow the application to resolve external entities.
  44         #
  45         # The parser will call this method before opening any external
  46         # entity except the top-level document entity. Such entities include
  47         # the external DTD subset and external parameter entities referenced
  48         # within the DTD (in either case, only if the parser reads external
  49         # parameter entities), and external general entities referenced
  50         # within the document element (if the parser reads external general
  51         # entities). The application may request that the parser locate
  52         # the entity itself, that it use an alternative URI, or that it
  53         # use data provided by the application (as a character or byte
  54         # input stream).
  55         #
  56         # Application writers can use this method to redirect external
  57         # system identifiers to secure and/or local URIs, to look up
  58         # public identifiers in a catalogue, or to read an entity from a
  59         # database or other input source (including, for example, a dialog
  60         # box). Neither XML nor SAX specifies a preferred policy for using
  61         # public or system IDs to resolve resources. However, SAX specifies
  62         # how to interpret any InputSource returned by this method, and that
  63         # if none is returned, then the system ID will be dereferenced as
  64         # a URL.
  65         #
  66         # If the system identifier is a URL, the SAX parser must
  67         # resolve it fully before reporting it to the application.
  68         #
  69         # Parameters:
  70         #
  71         # * `public_id`: public identifier of the external entity
  72         # being referenced, or `null` if none was supplied.
  73         # * `system_id`: system identifier of the external entity
  74         # being referenced.
  75         #
  76         # Returns:
  77         #
  78         # An `InputSource` object describing the new input source,
  79         # or `null` to request that the parser open a regular
  80         # URI connection to the system identifier.
  81         fun resolve_entity(public_id: nullable String, system_id: nullable String):
  82                         nullable InputSource do
  83                 return null
  84         end
  85 end