Package gov.nasa.worldwind.ogc.kml

Class KMLRoot

    • Field Detail

      • kmlDoc

        protected KMLDoc kmlDoc
        Reference to the KMLDoc representing the KML or KMZ file.

      • eventReader

        protected javax.xml.stream.XMLEventReader eventReader
        The event reader used to parse the document's XML.

      • eventStream

        protected java.io.InputStream eventStream
        The input stream underlying the event reader.

      • parserContext

        protected KMLParserContext parserContext
        The parser context for the document.

      • propertyChangeSupport

        protected java.beans.PropertyChangeSupport propertyChangeSupport
        The PropertyChangeSupport that receives property change events this KMLRoot listens for, and sends property change events to this KMLRoot's listeners. Lazily initialized in getChangeSupport. Initially null.

      • detailHint

        protected double detailHint
        Indicates this KML root's detail hint. Modifies the default relationship of KML scene resolution to screen resolution as viewing distance changes. Values greater than 0 increase the resolution. Values less than 0 decrease the resolution. Initially 0.

      • featureFetched

        protected boolean featureFetched
        Flag to indicate that the feature has been fetched from the hash map.

      • linkControlFetched

        protected boolean linkControlFetched
        Flag to indicate that the network link control element has been fetched from the hash map.

    • Constructor Detail

      • KMLRoot

        public KMLRoot​(KMLDoc docSource)
        throws java.io.IOException
        Create a new KMLRoot for a KMLDoc instance. A KMLDoc represents KML and KMZ files from either files or input streams.
        Parameters:
        docSource - the KMLDoc instance representing the KML document.
        Throws:
        java.lang.IllegalArgumentException - if the document source is null.
        java.io.IOException - if an error occurs while reading the KML document.

      • KMLRoot

        public KMLRoot​(KMLDoc docSource,
               boolean namespaceAware)
        throws java.io.IOException
        Create a new KMLRoot for a KMLDoc instance. A KMLDoc represents KML and KMZ files from either files or input streams.
        Parameters:
        docSource - the KMLDoc instance representing the KML document.
        namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.
        Throws:
        java.lang.IllegalArgumentException - if the document source is null.
        java.io.IOException - if an error occurs while reading the KML document.

      • KMLRoot

        public KMLRoot​(java.io.File docSource)
        throws java.io.IOException
        Create a new KMLRoot for a File.
        Parameters:
        docSource - the File containing the document.
        Throws:
        java.lang.IllegalArgumentException - if the document source is null.
        java.io.IOException - if an error occurs while reading the KML document.

      • KMLRoot

        public KMLRoot​(java.io.File docSource,
               boolean namespaceAware)
        throws java.io.IOException
        Create a new KMLRoot for a File.
        Parameters:
        docSource - the File containing the document.
        namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.
        Throws:
        java.lang.IllegalArgumentException - if the document source is null.
        java.io.IOException - if an error occurs while reading the KML document.

      • KMLRoot

        public KMLRoot​(java.io.InputStream docSource,
               java.lang.String contentType)
        throws java.io.IOException
        Create a new KMLRoot for an InputStream.
        Parameters:
        docSource - the input stream containing the document.
        contentType - the content type of the stream data. Specify KMLConstants.KML_MIME_TYPE for plain KML and KMLConstants.KMZ_MIME_TYPE for KMZ. The content is treated as KML for any other value or a value of null.
        Throws:
        java.lang.IllegalArgumentException - if the document source is null.
        java.io.IOException - if an error occurs while reading the KML document.

      • KMLRoot

        public KMLRoot​(java.io.InputStream docSource,
               java.lang.String contentType,
               boolean namespaceAware)
        throws java.io.IOException
        Create a new KMLRoot for an InputStream.
        Parameters:
        docSource - the input stream containing the document.
        contentType - the content type of the stream data. Specify KMLConstants.KML_MIME_TYPE for plain KML and KMLConstants.KMZ_MIME_TYPE for KMZ. The content is treated as KML for any other value or a value of null.
        namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.
        Throws:
        java.lang.IllegalArgumentException - if the document source is null.
        java.io.IOException - if an error occurs while reading the KML document.

      • KMLRoot

        public KMLRoot​(java.net.URL docSource,
               java.lang.String contentType)
        throws java.io.IOException
        Create a KMLRoot for a URL.
        Parameters:
        docSource - the URL identifying the document.
        contentType - the content type of the data. Specify KMLConstants.KML_MIME_TYPE for plain KML and KMLConstants.KMZ_MIME_TYPE for KMZ. Any other non-null value causes the content to be treated as plain KML. If null is specified the content type is read from the server or other end point of the URL. When a content type is specified, the content type returned by the URL's end point is ignored. You can therefore force the content to be treated as KML or KMZ regardless of what a server declares it to be.
        Throws:
        java.lang.IllegalArgumentException - if the document source is null.
        java.io.IOException - if an error occurs while reading the document.

      • KMLRoot

        public KMLRoot​(java.net.URL docSource,
               java.lang.String contentType,
               boolean namespaceAware)
        throws java.io.IOException
        Create a KMLRoot for a URL.
        Parameters:
        docSource - the URL identifying the document.
        contentType - the content type of the data. Specify KMLConstants.KML_MIME_TYPE for plain KML and KMLConstants.KMZ_MIME_TYPE for KMZ. Any other non-null value causes the content to be treated as plain KML. If null is specified the content type is read from the server or other end point of the URL. When a content type is specified, the content type returned by the URL's end point is ignored. You can therefore force the content to be treated as KML or KMZ regardless of what a server declares it to be.
        namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.
        Throws:
        java.lang.IllegalArgumentException - if the document source is null.
        java.io.IOException - if an error occurs while reading the document.

      • KMLRoot

        public KMLRoot​(java.lang.String namespaceURI,
               KMLDoc docSource)
        throws java.io.IOException
        Create a new KMLRoot with a specific namespace. (The default namespace is defined by KMLConstants.KML_NAMESPACE).
        Parameters:
        namespaceURI - the default namespace URI.
        docSource - the KML source specified via a KMLDoc instance. A KMLDoc represents KML and KMZ files from either files or input streams.
        Throws:
        java.lang.IllegalArgumentException - if the document source is null.
        java.io.IOException - if an I/O error occurs attempting to open the document source.

      • KMLRoot

        public KMLRoot​(java.lang.String namespaceURI,
               KMLDoc docSource,
               boolean namespaceAware)
        throws java.io.IOException
        Create a new KMLRoot with a specific namespace. (The default namespace is defined by KMLConstants.KML_NAMESPACE).
        Parameters:
        namespaceURI - the default namespace URI.
        docSource - the KML source specified via a KMLDoc instance. A KMLDoc represents KML and KMZ files from either files or input streams.
        namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.
        Throws:
        java.lang.IllegalArgumentException - if the document source is null.
        java.io.IOException - if an I/O error occurs attempting to open the document source.

    • Method Detail

      • create

        public static KMLRoot create​(java.lang.Object docSource)
                      throws java.io.IOException
        Creates a KML root for an untyped source. The source must be either a File, a URL, a InputStream, or a String identifying either a file path or a URL. For all types other than InputStream an attempt is made to determine whether the source is KML or KMZ; KML is assumed if the test is not definitive. Null is returned if the source type is not recognized.
        Parameters:
        docSource - either a File, a URL, or an InputStream, or a String identifying a file path or URL.
        Returns:
        a new KMLRoot for the specified source, or null if the source type is not supported.
        Throws:
        java.lang.IllegalArgumentException - if the source is null.
        java.io.IOException - if an error occurs while reading the source.

      • create

        public static KMLRoot create​(java.lang.Object docSource,
                             boolean namespaceAware)
                      throws java.io.IOException
        Creates a KML root for an untyped source. The source must be either a File, a URL, a InputStream, or a String identifying either a file path or a URL. For all types other than InputStream an attempt is made to determine whether the source is KML or KMZ; KML is assumed if the test is not definitive. Null is returned if the source type is not recognized.
        Parameters:
        docSource - either a File, a URL, or an InputStream, or a String identifying a file path or URL.
        namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.
        Returns:
        a new KMLRoot for the specified source, or null if the source type is not supported.
        Throws:
        java.lang.IllegalArgumentException - if the source is null.
        java.io.IOException - if an error occurs while reading the source.

      • createAndParse

        public static KMLRoot createAndParse​(java.lang.Object docSource)
                              throws java.io.IOException,
                                     javax.xml.stream.XMLStreamException
        Creates a KML root for an untyped source and parses it. The source must be either a File, a URL, a InputStream, or a String identifying either a file path or a URL. For all types other than InputStream an attempt is made to determine whether the source is KML or KMZ; KML is assumed if the test is not definitive. Null is returned if the source type is not recognized.

        Note: Because there are so many incorrectly formed KML files in distribution, it's often not possible to parse with a namespace aware parser. This method first tries to use a namespace aware parser, but if a severe problem occurs during parsing, it will try again using a namespace unaware parser. Namespace unaware parsing typically bypasses many problems, but it also causes namespace qualified elements in the XML to be unrecognized.

        Parameters:
        docSource - either a File, a URL, or an InputStream, or a String identifying a file path or URL.
        Returns:
        a new KMLRoot for the specified source, or null if the source type is not supported.
        Throws:
        java.lang.IllegalArgumentException - if the source is null.
        java.io.IOException - if an error occurs while reading the source.
        javax.xml.stream.XMLStreamException - if the KML file has severe errors.

      • initialize

        protected void initialize​(boolean namespaceAware)
                   throws java.io.IOException
        Called just before the constructor returns. If overriding this method be sure to invoke super.initialize(boolean).
        Parameters:
        namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.
        Throws:
        java.io.IOException - if an I/O error occurs attempting to open the document source.

      • createReader

        protected javax.xml.stream.XMLEventReader createReader​(java.lang.Object docSource,
                                                       boolean namespaceAware)
        Creates the event reader. Called from the constructor.
        Parameters:
        docSource - the document source to create a reader for. The type can be any of those supported by WWXML.openEventReader(Object).
        namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.
        Returns:
        a new event reader, or null if the source type cannot be determined.

      • createParserContext

        protected KMLParserContext createParserContext​(javax.xml.stream.XMLEventReader reader)
        Invoked during initialize(boolean) to create the parser context. The parser context is created by the global XMLEventParserContextFactory.
        Parameters:
        reader - the reader to associate with the parser context.
        Returns:
        a new parser context.

      • setNotificationListener

        public void setNotificationListener​(XMLParserNotificationListener listener)
        Specifies the object to receive notifications of important occurrences during parsing, such as exceptions and the occurrence of unrecognized element types.

        The default notification listener writes a message to the log, and otherwise does nothing.

        Parameters:
        listener - the listener to receive notifications. Specify null to indicate no listener.
        See Also:
        XMLParserNotification

      • getKMLDoc

        public KMLDoc getKMLDoc()
        Returns the KML document for this KMLRoot.
        Returns:
        the KML document for this root.

      • getItemByID

        public java.lang.Object getItemByID​(java.lang.String id)
        Finds a named element in the document.
        Parameters:
        id - the element's identifier. If null, null is returned.
        Returns:
        the element requested, or null if there is no corresponding element in the document.

      • getSupportFilePath

        public java.lang.String getSupportFilePath​(java.lang.String link)
                                    throws java.io.IOException
        Throws:
        java.io.IOException

      • resolveReference

        public java.lang.Object resolveReference​(java.lang.String link)
        Resolves a reference to a remote or local element of the form address#identifier, where "address" identifies a local or remote document, including the current document, and and "identifier" is the id of the desired element.

        If the address part identifies the current document, the document is searched for the specified identifier. Otherwise the document is retrieved, opened and searched for the identifier. If the address refers to a remote document and the document has not previously been retrieved and cached locally, retrieval is initiated and this method returns null. Once the document is successfully retrieved, subsequent calls to this method return the identified element, if it exists.

        If the link does not contain an identifier part, this initiates a retrieval for document referenced by the address part and returns null. Once the document is retrieved this opens the the document as a KMLRoot. Subsequent calls to this method return the opened document, if it exists.

        Parameters:
        link - the document address in the form address#identifier.
        Returns:
        the requested document, the requested or element within a document, or null if the document or the element are not found.
        Throws:
        java.lang.IllegalArgumentException - if the link is null.

      • resolveReference

        public java.lang.Object resolveReference​(java.lang.String link,
                                         boolean cacheRemoteFile)
        Resolves a reference to a remote or local element of the form address#identifier, where "address" identifies a local or remote document, including the current document, and and "identifier" is the id of the desired element.

        If the address part identifies the current document, the document is searched for the specified identifier. Otherwise the document is retrieved, opened and searched for the identifier. If the address refers to a remote document and the document has not previously been retrieved and cached locally, retrieval is initiated and this method returns null. Once the document is successfully retrieved, subsequent calls to this method return the identified element, if it exists.

        If the link does not contain an identifier part, this initiates a retrieval for document referenced by the address part and returns null. Once the document is retrieved this opens the the document as a KMLRoot. Subsequent calls to this method return the opened document, if it exists.

        The cacheRemoteFile parameter specifies whether to store a retrieved remote document in the World Wind cache or in a temporary location. This parameter has no effect if the document exists locally. The temporary location for a retrieved document does not persist between runtime sessions, and subsequent invocations of this method may not return the same temporary location.

        Parameters:
        link - the document address in the form address#identifier.
        cacheRemoteFile - true to store remote documents in the WorldWind cache, or false to store remote documents in a temporary location. Has no effect if the address is a local document.
        Returns:
        the requested document, the requested or element within a document, or null if the document or the element are not found.
        Throws:
        java.lang.IllegalArgumentException - if the link is null.

      • resolveLocalReference

        public java.lang.Object resolveLocalReference​(java.lang.String linkBase,
                                              java.lang.String linkRef)
        Resolves a reference to a local element identified by address and identifier, where linkBase identifies a document, including the current document, and linkRef is the id of the desired element.

        If linkBase refers to a local KML or KMZ file and linkRef is non-null, the return value is the element identified by linkRef. If linkRef is null, the return value is a parsed KMLRoot for the KML file identified by linkBase.

        If linkBase refers a local file that is not a KML or KMZ file then linkBase is returned. If linkBase cannot be resolved to a local file then null is returned.

        Parameters:
        linkBase - the address of the document containing the requested element.
        linkRef - the element's identifier.
        Returns:
        the requested element, or null if the element is not found.
        Throws:
        java.lang.IllegalArgumentException - if the address is null.

      • resolveRemoteReference

        public java.lang.Object resolveRemoteReference​(java.lang.String linkBase,
                                               java.lang.String linkRef)
        Resolves a reference to a remote element identified by address and identifier, where linkBase identifies a remote document, and linkRef is the id of the desired element. This method retrieves resources asynchronously using the FileStore.

        The return value is null if the file is not yet available in the FileStore. If linkBase refers to a KML or KMZ file and linkRef is non-null, the return value is the element identified by linkRef. If linkBase refers to a KML or KMZ and linkRef is null, the return value is a parsed KMLRoot for the KML file identified by linkBase. Otherwise the return value is a URL to the file in the file cache.

        Parameters:
        linkBase - the address of the document containing the requested element.
        linkRef - the element's identifier.
        Returns:
        URL to the requested file, parsed KMLRoot, or KML feature. Returns null if the document is not yet available in the FileStore.
        Throws:
        java.lang.IllegalArgumentException - if the linkBase is null.

      • resolveRemoteReference

        public java.lang.Object resolveRemoteReference​(java.lang.String linkBase,
                                               java.lang.String linkRef,
                                               boolean cacheRemoteFile)
        Resolves a reference to a remote element identified by address and identifier, where linkBase identifies a remote document, and linkRef is the id of the desired element. This method retrieves resources asynchronously using the FileStore.

        The return value is null if the file is not yet available in the FileStore. If linkBase refers to a KML or KMZ file and linkRef is non-null, the return value is the element identified by linkRef. If linkBase refers to a KML or KMZ and linkRef is null, the return value is a parsed KMLRoot for the KML file identified by linkBase. Otherwise the return value is a URL to the file in the file cache or a temporary location, depending on the value of cacheRemoteFile.

        The cacheRemoteFile parameter specifies whether to store a retrieved remote file in the WorldWind cache or in a temporary location. This parameter has no effect if the file exists locally. The temporary location for a retrieved file does not persist between runtime sessions, and subsequent invocations of this method may not return the same temporary location.

        Parameters:
        linkBase - the address of the document containing the requested element.
        linkRef - the element's identifier.
        cacheRemoteFile - true to store remote files in the WorldWind cache, or false to store remote files in a temporary location. Has no effect if the address is a local file.
        Returns:
        URL to the requested file, parsed KMLRoot, or KML feature. Returns null if the document is not yet available in the FileStore.
        Throws:
        java.lang.IllegalArgumentException - if the linkBase is null.

      • resolveNetworkLink

        public java.lang.Object resolveNetworkLink​(java.lang.String link,
                                           boolean cacheRemoteFile,
                                           long updateTime)
        Resolves a NetworkLink to a local or remote KML document. This method retrieves remote resources asynchronously using the FileStore.

        The return value is a parsed KMLRoot representing the linked document. The return value is null if the linked file is not a KML file, or is not yet available in the FileStore.

        The cacheRemoteFile parameter specifies whether to store a retrieved remote file in the WorldWind cache or in a temporary location. This parameter has no effect if the file exists locally. The temporary location for a retrieved file does not persist between runtime sessions, and subsequent invocations of this method may not return the same temporary location.

        Parameters:
        link - the address to resolve
        cacheRemoteFile - true to store remote files in the WorldWind cache, or false to store remote files in a temporary location. Has no effect if the address is a local file.
        updateTime - the time at which the link was last updated. If a cached file exists for the specified resource, the file must have been retrieved after the link update time. Otherwise, the cache entry is considered invalid, and the file is deleted and retrieved again.
        Returns:
        URL to the requested file, parsed KMLRoot, or KML feature. Returns null if the document is not yet available in the FileStore.
        Throws:
        java.lang.IllegalArgumentException - if the link is null.

      • evictIfExpired

        public void evictIfExpired​(java.lang.String link,
                           long expirationTime)
        Check a cached resource for expiration. If the resource is expired, evict it from the cache.
        Parameters:
        link - Link that identifies the resource to check for expiration. This is the same link that was passed to resolveReference to retrieve the resource.
        expirationTime - Time at which the resource expires, in milliseconds since the Epoch. If the current system time is greater than the expiration time, then the resource will be evicted.

      • getExpiration

        public long getExpiration​(java.lang.String link)
        Returns the expiration time of a file retrieved by resolveReference or resolveNetworkLink.
        Parameters:
        link - the address of the file (the same address as was previously passed to resolveReference). If null, zero is returned.
        Returns:
        The expiration time of the file, in milliseconds since the Epoch (January 1, 1970, 00:00:00 GMT). Zero indicates that there is no expiration time. Returns zero if te resource identified by link has not been retrieved.

      • canParseContentType

        protected boolean canParseContentType​(java.lang.String mimeType)
        Determines if a MIME type can be parsed as KML or KMZ. Parsable types are the KML and KMZ MIME types, as well as "text/plain" and "text/xml".
        Parameters:
        mimeType - Type to test. May be null.
        Returns:
        true if mimeType can be parsed as KML.

      • parseCachedKMLFile

        protected KMLRoot parseCachedKMLFile​(java.net.URL url,
                                     java.lang.String linkBase,
                                     java.lang.String contentType,
                                     boolean namespaceAware)
                              throws java.io.IOException,
                                     javax.xml.stream.XMLStreamException
        Open and parse the specified file expressed as a file: URL..
        Parameters:
        url - the URL of the file to open, expressed as a URL with a scheme of "file".
        linkBase - the original address of the document if the file is a retrieved and cached file.
        contentType - the mime type of the file's content, either a KML or KMZ mime type.
        namespaceAware - specifies whether to use a namespace aware event reader.
        Returns:
        A KMLRoot representing the file's KML contents.
        Throws:
        java.io.IOException - if an I/O error occurs during opening and parsing.
        javax.xml.stream.XMLStreamException - if a server parsing error is encountered.

      • parse

        public KMLRoot parse​(java.lang.Object... args)
              throws javax.xml.stream.XMLStreamException
        Starts document parsing. This method initiates parsing of the KML document and returns when the full document has been parsed.
        Parameters:
        args - optional arguments to pass to parsers of sub-elements.
        Returns:
        this if parsing is successful, otherwise null.
        Throws:
        javax.xml.stream.XMLStreamException - if an exception occurs while attempting to read the event stream.

      • closeEventStream

        protected void closeEventStream()
        Closes the event stream associated with this context's XML event reader.

      • getHint

        public java.lang.String getHint()
        Returns the hint attribute of the KML element (the document root).
        Returns:
        the hint attribute, or null if the attribute is not specified.

      • getNetworkLinkControl

        public KMLNetworkLinkControl getNetworkLinkControl()
        Returns the KMLNetworkLinkControl element if the document root contains it.
        Returns:
        the element if it is specified in the document, otherwise null.

      • getFeature

        public KMLAbstractFeature getFeature()
        Returns the KML Feature element contained in the document root.
        Returns:
        the feature element if it is specified in the document, otherwise null.

      • findFeature

        protected KMLAbstractFeature findFeature()
        Searches this root's fields for the KML Feature element.
        Returns:
        the feature element, or null if none was found.

      • setDetailHint

        public void setDetailHint​(double detailHint)
        Specifies this KML root's detail hint. The detail hint modifies the default relationship of KML scene resolution to screen resolution as the viewing distance changes. Values greater than 0 cause KML elements with a level of detail to appear at higher resolution at greater distances than normal, but at an increased performance cost. Values less than 0 decrease the default resolution at any given distance. The default value is 0. Values typically range between -0.5 and 0.5.

        The top level KML root's detail hint is inherited by all KML elements beneath that root, including any descendant KML roots loaded by network links. If this KML root has been loaded by a network link, its detail hint is ignored.

        Parameters:
        detailHint - the degree to modify the default relationship of KML scene resolution to screen resolution as viewing distance changes. Values greater than 0 increase the resolution. Values less than 0 decrease the resolution. The default value is 0.

      • requestRedraw

        public void requestRedraw()
        Request any scene containing this KML document be repainted.

      • onMessage

        public void onMessage​(Message msg)
        Invoked when a message is received.

        Overridden to forward the message to the root feature.

        Specified by:
        onMessage in interface MessageListener
        Overrides:
        onMessage in class KMLAbstractObject
        Parameters:
        msg - The message that was received.

      • addPropertyChangeListener

        public void addPropertyChangeListener​(java.beans.PropertyChangeListener listener)
        Adds the specified property change listener that will be called for all list changes.
        Parameters:
        listener - the listener to call.
        Throws:
        java.lang.IllegalArgumentException - if listener is null
        See Also:
        PropertyChangeSupport

      • removePropertyChangeListener

        public void removePropertyChangeListener​(java.beans.PropertyChangeListener listener)
        Removes the specified property change listener.
        Parameters:
        listener - the listener to remove.
        Throws:
        java.lang.IllegalArgumentException - if listener is null.
        See Also:
        PropertyChangeSupport

      • firePropertyChange

        public void firePropertyChange​(java.beans.PropertyChangeEvent propertyChangeEvent)
        Fire a property change event.
        Parameters:
        propertyChangeEvent - Event to fire.

      • firePropertyChange

        public void firePropertyChange​(java.lang.String propertyName,
                               java.lang.Object oldValue,
                               java.lang.Object newValue)
        Fire a property change event.
        Parameters:
        propertyName - Name of the property change changed.
        oldValue - The previous value of the property.
        newValue - The new value of the property.

      • getChangeSupport

        protected java.beans.PropertyChangeSupport getChangeSupport()
        Get the PropertyChangeSupport object for this KML object. The support object will be created if it does not already exist.
        Returns:
        PropertyChangeSupport for this KML object.