001 /*
002 * Copyright 2005 Niclas Hedhman
003 * Copyright 2005 Stephen McConnell
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
014 * implied.
015 *
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019
020 package net.dpml.transit.link;
021
022 import java.io.IOException;
023
024 import java.net.URI;
025
026 import net.dpml.transit.NullArgumentException;
027
028 /**
029 * The Link class is a data structure that holds the target uri of a link.
030 *
031 * It is not intended that the applications instantiates this class directly,
032 * but obtains it as a object from the <code>URL.getContent()</code> method.
033 * Example;
034 *
035 * <pre><code>
036 * URL url = new URL( "link:jar:some/opague/pointer" );
037 * Class[] type = new Class[] { Link.class };
038 *
039 * // Get the Link object from the URL
040 * Link link = (Link) url.getContent( type );
041 *
042 * // Get the URI that this link is pointing to at the moment
043 * URI uri = link.getTargetURI();
044 *
045 * // Change the link to point somewhere else.
046 * URI newUri = new URI( "artifact:jar:abc/def/hoopla#3.1.2" );
047 * link.setTargetURI( newUri );
048 * </code></pre>
049 * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
050 * @version 1.1.0
051 */
052 public class Link
053 {
054 private final LinkManager m_manager;
055 private final URI m_uri;
056
057 /**
058 * Constructor for the Link.
059 * @param uri the link physical uri
060 * @param manager the link manager
061 * @exception NullArgumentException if the link uri or manager is null
062 */
063 public Link( URI uri, LinkManager manager ) throws NullArgumentException
064 {
065 if( null == manager )
066 {
067 throw new NullArgumentException( "manager" );
068 }
069 if( null == uri )
070 {
071 throw new NullArgumentException( "uri" );
072 }
073
074 m_manager = manager;
075 m_uri = uri;
076 }
077
078 /**
079 * Return the link uri.
080 * @return the link uri value
081 */
082 public URI getLinkURI()
083 {
084 return m_uri;
085 }
086
087 /**
088 * Return the URI that is currently bound to the Link.
089 * @param defaultUri the default value
090 * @return the current URI the link: is pointing to.
091 * @exception IOException if an IO error occurs
092 */
093 public URI getTargetURI( URI defaultUri ) throws IOException
094 {
095 try
096 {
097 return m_manager.getTargetURI( m_uri );
098 }
099 catch( LinkNotFoundException e )
100 {
101 return defaultUri;
102 }
103 }
104
105 /**
106 * Sets (and permanently remembers) the Link to point to a new URI.
107 * @param uri the URI that this link: should be pointing to.
108 * @exception IOException if an IO error occurs
109 */
110 public void setTargetURI( URI uri ) throws IOException
111 {
112 m_manager.setTargetURI( m_uri, uri );
113 }
114 }
115