001    /*
002     * Created on Oct 29, 2007
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with the License. You may obtain a copy of the License at
006     *
007     * http://www.apache.org/licenses/LICENSE-2.0
008     *
009     * Unless required by applicable law or agreed to in writing, software distributed under the License
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     *
014     * Copyright @2007-2010 the original author or authors.
015     */
016    package org.fest.swing.finder;
017    
018    import java.awt.Component;
019    import java.util.concurrent.TimeUnit;
020    
021    import javax.swing.JFileChooser;
022    
023    import org.fest.swing.core.GenericTypeMatcher;
024    import org.fest.swing.core.Robot;
025    import org.fest.swing.fixture.JFileChooserFixture;
026    
027    /**
028     * Understands a finder for <code>{@link JFileChooser}</code>s. Lookups are performed till a file chooser is found,
029     * or until the given time to perform the lookup is over. The default lookup time is 5 seconds.
030     * </p>
031     * <p>
032     * This example illustrates finding a <code>{@link JFileChooser}</code> by name, using the default lookup time (5
033     * seconds):
034     *
035     * <pre>
036     * JFileChooserFixture fileChooser = JFileChooserFinder.findFileChooser().using(robot);
037     * </pre>
038     *
039     * </p>
040     * <p>
041     * Where <code>robot</code> is an instance of <code>{@link org.fest.swing.core.Robot}</code>.
042     * </p>
043     * <p>
044     * This example shows how to find a <code>{@link JFileChooser}</code> by type using a lookup time of 10 seconds:
045     *
046     * <pre>
047     * JFileChooserFixture fileChooser = JFileChooserFinder.findFileChooser().withTimeout(10000).using(robot);
048     * </pre>
049     *
050     * We can also specify the time unit:
051     *
052     * <pre>
053     * JFileChooserFixture fileChooser = JFileChooserFinder.findFileChooser().withTimeout(10, {@link java.util.concurrent.TimeUnit#SECONDS SECONDS}).using(robot);
054     * </pre>
055     *
056     * </p>
057     * <p>
058     * This examples shows how to find a <code>{@link JFileChooser}</code> using a <code>{@link GenericTypeMatcher}</code>:
059     *
060     * <pre>
061     * GenericTypeMatcher&lt;JFileChooser&gt; matcher = new GenericTypeMatcher&lt;JFileChooser&gt;() {
062     *   protected boolean isMatching(JFileChooser fileChooser) {
063     *     return fileChooser.getCurrentDirectory().getAbsolutePath().equals(&quot;c:\\temp&quot;);
064     *   }
065     * };
066     * JFileChooserFixture fileChooser = JFileChooserFinder.findFileChooser(matcher).using(robot);
067     * </pre>
068     *
069     * </p>
070     *
071     * @author Alex Ruiz
072     */
073    public class JFileChooserFinder extends ComponentFinderTemplate<JFileChooser> {
074    
075      /**
076       * Creates a new </code>{@link JFileChooserFinder}</code>. This finder looks up a <code>{@link JFileChooser}</code> by
077       * type.
078       */
079      protected JFileChooserFinder() {
080        super(JFileChooser.class);
081      }
082    
083      /**
084       * Creates a new </code>{@link JFileChooserFinder}</code>.
085       * @param name the name of the {@code FileChooser} to look for.
086       */
087      protected JFileChooserFinder(String name) {
088        super(name, JFileChooser.class);
089      }
090    
091      /**
092       * Creates a new </code>{@link JFileChooserFinder}</code>.
093       * @param matcher specifies the search criteria to use when looking up a {@code JFileChooser}.
094       */
095      protected JFileChooserFinder(GenericTypeMatcher<? extends JFileChooser> matcher) {
096        super(matcher);
097      }
098    
099      /**
100       * Creates a new <code>{@link JFileChooserFinder}</code> capable of looking up a <code>{@link JFileChooser}</code>.
101       * @return the created finder.
102       */
103      public static JFileChooserFinder findFileChooser() {
104        return new JFileChooserFinder();
105      }
106    
107      /**
108       * Creates a new <code>{@link JFileChooserFinder}</code> capable of looking up a <code>{@link JFileChooser}</code> by
109       * name.
110       * @param name the name of the file chooser to find.
111       * @return the created finder.
112       */
113      public static JFileChooserFinder findFileChooser(String name) {
114        return new JFileChooserFinder(name);
115      }
116    
117      /**
118       * Creates a new <code>{@link JFileChooserFinder}</code> capable of looking up a <code>{@link JFileChooser}</code>
119       * using the given matcher.
120       * @param matcher the given matcher.
121       * @return the created finder.
122       */
123      public static JFileChooserFinder findFileChooser(GenericTypeMatcher<? extends JFileChooser> matcher) {
124        return new JFileChooserFinder(matcher);
125      }
126    
127      /**
128       * Finds a <code>{@link JFileChooser}</code> by name or type.
129       * @param robot contains the underlying finding to delegate the search to.
130       * @return a <code>JFileChooserFixture</code> managing the found {@code JFileChooser}.
131       * @throws org.fest.swing.exception.WaitTimedOutError if a {@code JFileChooser} could not be found.
132       */
133      public JFileChooserFixture using(Robot robot) {
134        return new JFileChooserFixture(robot, findComponentWith(robot));
135      }
136    
137      /**
138       * Sets the timeout for this finder. The <code>{@link JFileChooser}</code> to find should be found within the given
139       * time period.
140       * @param timeout the number of milliseconds before stopping the search.
141       * @return this finder.
142       * @throws IllegalArgumentException if the timeout is a negative number.
143       */
144      @Override public JFileChooserFinder withTimeout(long timeout) {
145        super.withTimeout(timeout);
146        return this;
147      }
148    
149      /**
150       * Sets the timeout for this finder. The <code>{@link JFileChooser}</code> to find should be found within the given
151       * time period.
152       * @param timeout the period of time the search should be performed.
153       * @param unit the time unit for <code>timeout</code>.
154       * @return this finder.
155       * @throws NullPointerException if the time unit is <code>null</code>.
156       * @throws IllegalArgumentException if the timeout is a negative number.
157       */
158      @Override public JFileChooserFinder withTimeout(long timeout, TimeUnit unit) {
159        super.withTimeout(timeout, unit);
160        return this;
161      }
162    
163      /**
164       * Casts the given {@code Component} to <code>{@link JFileChooser}</code>.
165       * @return the given {@code Component}, casted to {@code JFileChooser}.
166       */
167      protected JFileChooser cast(Component c) { return (JFileChooser) c; }
168    }