001/* An actor that reads a String input token naming a URL and outputs
002 an Image of type Object.
003
004 @Copyright (c) 2001-2014 The Regents of the University of California.
005 All rights reserved.
006
007 Permission is hereby granted, without written agreement and without
008 license or royalty fees, to use, copy, modify, and distribute this
009 software and its documentation for any purpose, provided that the
010 above copyright notice and the following two paragraphs appear in all
011 copies of this software.
012
013 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
014 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
015 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
016 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
017 SUCH DAMAGE.
018
019 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
020 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
021 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
022 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
023 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
024 ENHANCEMENTS, OR MODIFICATIONS.
025
026 PT_COPYRIGHT_VERSION 2
027 COPYRIGHTENDKEY
028 */
029package ptolemy.actor.lib.image;
030
031import java.awt.Image;
032import java.io.IOException;
033import java.net.MalformedURLException;
034import java.net.URL;
035
036import javax.imageio.ImageIO;
037
038import ptolemy.actor.lib.Transformer;
039import ptolemy.data.AWTImageToken;
040import ptolemy.data.StringToken;
041import ptolemy.data.type.BaseType;
042import ptolemy.kernel.CompositeEntity;
043import ptolemy.kernel.util.IllegalActionException;
044import ptolemy.kernel.util.NameDuplicationException;
045
046///////////////////////////////////////////////////////////////////
047//// URLToImage
048
049/**
050 <p>An actor that reads a String input token naming a URL and outputs an
051 Object Token that contains a java.awt.Image</p>
052
053 <p>It is possible to load a file
054 from the local file system by using the prefix "file://" instead of
055 "http://". Relative file paths are allowed. To specify a file
056 relative to the current directory, use "../" or "./". For example,
057 if the current directory contains a file called "test.jpg", then
058 <i>sourceURL</i> should be set to "file:./test.jpg". If the parent
059 directory contains a file called "test.jpg", then <i>sourceURL</i>
060 should be set to "file:../test.jpg". To reference the file
061 test.jpg, located at "/tmp/test.jpg", <i>sourceURL</i>
062 should be set to "file:///tmp/test.jpg" The default value is
063 "file:///tmp/test.jpg".</p>
064
065 @see ImageReader
066 @author  Christopher Hylands
067 @version $Id$
068 @since Ptolemy II 3.0
069 @Pt.ProposedRating Red (cxh)
070 @Pt.AcceptedRating Red (cxh)
071 */
072public class URLToImage extends Transformer {
073    /** Construct an actor with the given container and name.
074     *  @param container The container.
075     *  @param name The name of this actor.
076     *  @exception IllegalActionException If the actor cannot be contained
077     *   by the proposed container.
078     *  @exception NameDuplicationException If the container already has an
079     *   actor with this name.
080     */
081    public URLToImage(CompositeEntity container, String name)
082            throws IllegalActionException, NameDuplicationException {
083        super(container, name);
084
085        output.setTypeEquals(BaseType.OBJECT);
086        input.setTypeEquals(BaseType.STRING);
087    }
088
089    ///////////////////////////////////////////////////////////////////
090    ////                         public methods                    ////
091
092    /** Read on StringToken from the input, and output an ObjectToken
093     *  that contains a java.awt.Image object to the output port.
094     *  @exception IllegalActionException If there's no director.
095     */
096    @Override
097    public void fire() throws IllegalActionException {
098        super.fire();
099        StringToken urlToken = (StringToken) input.get(0);
100
101        try {
102            URL url = new URL(urlToken.stringValue());
103            Image image = ImageIO.read(url);
104            output.send(0, new AWTImageToken(image));
105        } catch (MalformedURLException ex) {
106            throw new IllegalActionException(this, ex,
107                    "'" + urlToken.stringValue() + "' is malformed.");
108        } catch (IOException e) {
109            throw new IllegalActionException(this, e, "Failed to read image.");
110        }
111    }
112
113    /** Return false if the input port has no token, otherwise return
114     *  what the superclass returns (presumably true).
115     *  @exception IllegalActionException If there is no director.
116     */
117    @Override
118    public boolean prefire() throws IllegalActionException {
119        if (!input.hasToken(0)) {
120            return false;
121        }
122
123        return super.prefire();
124    }
125}