netbeans/jemmy/FrameWaiter.java

/*
 * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package org.netbeans.jemmy;

import java.awt.Component;
import java.awt.Frame;

/**
 *
 * Contains methods to search and wait Frame. A FrameWaiter is a utility class
 * used to look or wait for Frames. It contains methods to search for a Frame
 * among the currently showing Frames as well as methods that wait for a Frame
 * to show within an allotted time period.
 *
 * <BR><BR>Timeouts used: <BR>
 * FrameWaiter.WaitFrameTimeout - time to wait frame displayed. <BR>
 * FrameWaiter.AfterFrameTimeout - time to sleep after frame has been displayed.
 * <BR>
 *
 * @see org.netbeans.jemmy.Timeouts
 *
 * @author Alexandre Iline (alexandre.iline@oracle.com)
 */
public class FrameWaiter extends WindowWaiter implements Timeoutable, Outputable {

    private final static long WAIT_TIME = 60000;
    private final static long AFTER_WAIT_TIME = 0;

    private Timeouts timeouts;
    private TestOut output;

    /**
     * Constructor.
     */
    public FrameWaiter() {
        super();
        setTimeouts(JemmyProperties.getProperties().getTimeouts());
        setOutput(JemmyProperties.getProperties().getOutput());
    }

    /**
     * Searches for a Frame. Search among the currently showing Frames for one
     * that meets the search criteria applied by the
     * {@code ComponentChooser} parameter.
     *
     * @param cc A component chooser used to define and apply the search
     * criteria.
     * @return a reference to the first Frame that is showing and that meets the
     * search criteria. If no such Frame can be found, a {@code null}
     * reference is returned.
     */
    public static Frame getFrame(ComponentChooser cc) {
        return (Frame) WindowWaiter.getWindow(new FrameSubChooser(cc));
    }

    /**
     * Searches for a Frame. The search proceeds among the currently showing
     * Frames for the {@code index+1}'th Frame that meets the criteria
     * defined and applied by the {@code ComonentChooser} parameter.
     *
     * @param cc A component chooser used to define and apply the search
     * criteria.
     * @param index The ordinal index of the Frame in the set of currently
     * displayed Frames. The first index is 0.
     * @return a reference to the {@code index+1}'th Frame that is showing
     * and that meets the search criteria. If there are fewer than
     * {@code index+1} Frames, a {@code null} reference is returned.
     */
    public static Frame getFrame(ComponentChooser cc, int index) {
        return (Frame) WindowWaiter.getWindow(new FrameSubChooser(cc), index);
    }

    /**
     * Searches for a Frame by title. The search proceeds among the currently
     * showing Frames for the first with a suitable title.
     *
     * @param title Frame title or subtitle.
     * @param ce If {@code true} and the search is case sensitive, then a
     * match occurs when the {@code title} argument is a substring of a
     * Frame title. If {@code false} and the search is case sensitive, then
     * the {@code title} argument and the Frame title must be the same. If
     * {@code true} and the search is case insensitive, then a match occurs
     * when the {@code title} argument is a substring of the Frame title
     * after changing both to upper case. If {@code false} and the search
     * is case insensitive, then a match occurs when the {@code title}
     * argument is a substring of the Frame title after changing both to upper
     * case.
     * @param cc If {@code true} the search is case sensitive; otherwise,
     * the search is case insensitive.
     * @return a reference to the first Frame that is showing and that has a
     * suitable title. If no such Frame can be found, a {@code null}
     * reference is returned.
     */
    public static Frame getFrame(String title, boolean ce, boolean cc) {
        return (Frame) WindowWaiter.getWindow(new FrameByTitleChooser(title, ce, cc));
    }

    /**
     * Searches for a Frame by title. The search is for the
     * {@code index+1}'th Frame among the currently showing Frames that
     * possess a suitable title.
     *
     * @param title Frame title or subtitle.
     * @param ce If {@code true} and the search is case sensitive, then a
     * match occurs when the {@code title} argument is a substring of a
     * Frame title. If {@code false} and the search is case sensitive, then
     * the {@code title} argument and the Frame title must be the same. If
     * {@code true} and the search is case insensitive, then a match occurs
     * when the {@code title} argument is a substring of the Frame title
     * after changing both to upper case. If {@code false} and the search
     * is case insensitive, then a match occurs when the {@code title}
     * argument is a substring of the Frame title after changing both to upper
     * case.
     * @param cc If {@code true} the search is case sensitive; otherwise,
     * the search is case insensitive.
     * @param index The ordinal index of the Frame in the set of currently
     * displayed Frames. The first index is 0.
     * @return a reference to the {@code index+1}'th Frame that is showing
     * and that has a suitable title. If there are fewer than
     * {@code index+1} Frames, a {@code null} reference is returned.
     */
    public static Frame getFrame(String title, boolean ce, boolean cc, int index) {
        return (Frame) WindowWaiter.getWindow(new FrameByTitleChooser(title, ce, cc), index);
    }

    static {
        Timeouts.initDefault("FrameWaiter.WaitFrameTimeout", WAIT_TIME);
        Timeouts.initDefault("FrameWaiter.AfterFrameTimeout", AFTER_WAIT_TIME);
    }

    /**
     * Defines current timeouts.
     *
     * @param timeouts A collection of timeout assignments.
     * @see org.netbeans.jemmy.Timeoutable
     * @see org.netbeans.jemmy.Timeouts
     * @see #getTimeouts
     */
    @Override
    public void setTimeouts(Timeouts timeouts) {
        this.timeouts = timeouts;
        Timeouts times = timeouts.cloneThis();
        times.setTimeout("WindowWaiter.WaitWindowTimeout",
                timeouts.getTimeout("FrameWaiter.WaitFrameTimeout"));
        times.setTimeout("WindowWaiter.AfterWindowTimeout",
                timeouts.getTimeout("FrameWaiter.AfterFrameTimeout"));
        super.setTimeouts(times);
    }

    /**
     * Return current timeouts.
     *
     * @return the collection of current timeout assignments.
     * @see org.netbeans.jemmy.Timeoutable
     * @see org.netbeans.jemmy.Timeouts
     * @see #setTimeouts
     */
    @Override
    public Timeouts getTimeouts() {
        return timeouts;
    }

    /**
     * Defines print output streams or writers.
     *
     * @param output Identify the streams or writers used for print output.
     * @see org.netbeans.jemmy.Outputable
     * @see org.netbeans.jemmy.TestOut
     * @see #getOutput
     */
    @Override
    public void setOutput(TestOut output) {
        this.output = output;
        super.setOutput(output);
    }

    /**
     * Returns print output streams or writers.
     *
     * @return an object that contains references to objects for printing to
     * output and err streams.
     * @see org.netbeans.jemmy.Outputable
     * @see org.netbeans.jemmy.TestOut
     * @see #setOutput
     */
    @Override
    public TestOut getOutput() {
        return output;
    }

    /**
     * Waits for a Frame to show. Wait for the {@code index+1}'th Frame
     * that meets the criteria defined and applied by the
     * {@code ComonentChooser} parameter to show up.
     *
     * @param ch A component chooser used to define and apply the search
     * criteria.
     * @param index The ordinal index of the Frame in the set of currently
     * displayed Frames. The first index is 0.
     * @return a reference to the {@code index+1}'th Frame that shows and
     * that meets the search criteria. If fewer than {@code index+1} Frames
     * show up in the allotted time period then a {@code null} reference is
     * returned.
     * @throws TimeoutExpiredException
     * @see org.netbeans.jemmy.WindowWaiter#actionProduced(Object)
     * @exception InterruptedException
     */
    public Frame waitFrame(ComponentChooser ch, int index)
            throws InterruptedException {
        setTimeouts(timeouts);
        return (Frame) waitWindow(new FrameSubChooser(ch), index);
    }

    /**
     * Waits for a Frame to show. Wait for a Frame that meets the search
     * criteria applied by the {@code ComponentChooser} parameter to show
     * up.
     *
     * @param ch A component chooser used to define and apply the search
     * criteria.
     * @return a reference to the first Frame that shows and that meets the
     * search criteria. If no such Frame can be found within the time period
     * allotted, a {@code null} reference is returned.
     * @throws TimeoutExpiredException
     * @see org.netbeans.jemmy.WindowWaiter#actionProduced(Object)
     * @exception InterruptedException
     */
    public Frame waitFrame(ComponentChooser ch)
            throws InterruptedException {
        return waitFrame(ch, 0);
    }

    /**
     * Waits for a Frame to show. Wait for the {@code index+1}'th Frame to
     * show with a suitable title.
     *
     * @param title Frame title or subtitle.
     * @param compareExactly If {@code true} and the search is case
     * sensitive, then a match occurs when the {@code title} argument is a
     * substring of a Frame title. If {@code false} and the search is case
     * sensitive, then the {@code title} argument and the Frame title must
     * be the same. If {@code true} and the search is case insensitive,
     * then a match occurs when the {@code title} argument is a substring
     * of the Frame title after changing both to upper case. If
     * {@code false} and the search is case insensitive, then a match
     * occurs when the {@code title} argument is a substring of the Frame
     * title after changing both to upper case.
     * @param compareCaseSensitive If {@code true} the search is case
     * sensitive; otherwise, the search is case insensitive.
     * @param index The ordinal index of the Frame in the set of currently
     * displayed Frames with the proper window ownership and a suitable title.
     * The first index is 0.
     * @return a reference to the {@code index+1}'th Frame to show and that
     * has a suitable title. If no such Frame can be found within the time
     * period allotted, a {@code null} reference is returned.
     * @throws TimeoutExpiredException
     * @see org.netbeans.jemmy.WindowWaiter#actionProduced(Object)
     * @exception InterruptedException
     */
    public Frame waitFrame(String title, boolean compareExactly, boolean compareCaseSensitive, int index)
            throws InterruptedException {
        return waitFrame(new FrameByTitleChooser(title, compareExactly, compareCaseSensitive), index);
    }

    /**
     * Waits for a Frame to show. Wait for the first Frame to show with a
     * suitable title.
     *
     * @param title Frame title or subtitle.
     * @param compareExactly If {@code true} and the search is case
     * sensitive, then a match occurs when the {@code title} argument is a
     * substring of a Frame title. If {@code false} and the search is case
     * sensitive, then the {@code title} argument and the Frame title must
     * be the same. If {@code true} and the search is case insensitive,
     * then a match occurs when the {@code title} argument is a substring
     * of the Frame title after changing both to upper case. If
     * {@code false} and the search is case insensitive, then a match
     * occurs when the {@code title} argument is a substring of the Frame
     * title after changing both to upper case.
     * @param compareCaseSensitive If {@code true} the search is case
     * sensitive; otherwise, the search is case insensitive.
     * @return a reference to the first Frame to show and that has a suitable
     * title. If no such Frame can be found within the time period allotted, a
     * {@code null} reference is returned.
     * @throws TimeoutExpiredException
     * @see org.netbeans.jemmy.WindowWaiter#actionProduced(Object)
     * @exception InterruptedException
     */
    public Frame waitFrame(String title, boolean compareExactly, boolean compareCaseSensitive)
            throws InterruptedException {
        return waitFrame(title, compareExactly, compareCaseSensitive, 0);
    }

    /**
     * @see Waiter#getWaitingStartedMessage()
     */
    @Override
    protected String getWaitingStartedMessage() {
        return "Start to wait frame \"" + getComponentChooser().getDescription() + "\" opened";
    }

    /**
     * Overrides WindowWaiter.getTimeoutExpiredMessage. Returns the timeout
     * expired message value.
     *
     * @param timeSpent Time spent for waiting
     * @return a message tring
     * @see Waiter#getTimeoutExpiredMessage(long)
     */
    @Override
    protected String getTimeoutExpiredMessage(long timeSpent) {
        return ("Frame \"" + getComponentChooser().getDescription() + "\" has not been opened in "
                + timeSpent + " milliseconds");
    }

    /**
     * Overrides WindowWaiter.getActionProducedMessage. Returns the action
     * produced message value.
     *
     * @param timeSpent Time spent for waiting.
     * @param result A message string.
     * @return a message tring
     * @see Waiter#getActionProducedMessage(long, Object)
     */
    @Override
    protected String getActionProducedMessage(long timeSpent, final Object result) {
        String resultToString = null;
        if (result instanceof Component) {
            // run toString in dispatch thread
            resultToString = new QueueTool().invokeSmoothly(
                    new QueueTool.QueueAction<String>("result.toString()") {
                @Override
                public String launch() {
                    return result.toString();
                }
            }
            );
        } else {
            resultToString = result.toString();
        }
        return ("Frame \"" + getComponentChooser().getDescription() + "\" has been opened in "
                + timeSpent + " milliseconds"
                + "\n    " + resultToString);
    }

    /**
     * @see Waiter#getGoldenWaitingStartedMessage()
     */
    @Override
    protected String getGoldenWaitingStartedMessage() {
        return "Start to wait frame \"" + getComponentChooser().getDescription() + "\" opened";
    }

    /**
     * @see Waiter#getGoldenTimeoutExpiredMessage()
     */
    @Override
    protected String getGoldenTimeoutExpiredMessage() {
        return "Frame \"" + getComponentChooser().getDescription() + "\" has not been opened";
    }

    /**
     * @see Waiter#getGoldenActionProducedMessage()
     */
    @Override
    protected String getGoldenActionProducedMessage() {
        return "Frame \"" + getComponentChooser().getDescription() + "\" has been opened";
    }

    private static class FrameSubChooser implements ComponentChooser {

        private ComponentChooser chooser;

        public FrameSubChooser(ComponentChooser c) {
            super();
            chooser = c;
        }

        @Override
        public boolean checkComponent(Component comp) {
            if (comp instanceof Frame) {
                return ((FIND_INVISIBLE_WINDOWS || (comp.isShowing() && comp.isVisible()))
                        && chooser.checkComponent(comp));
            } else {
                return false;
            }
        }

        @Override
        public String getDescription() {
            return chooser.getDescription();
        }

        @Override
        public String toString() {
            return "FrameSubChooser{" + "chooser=" + chooser + '}';
        }
    }

    private static class FrameByTitleChooser implements ComponentChooser {

        String title;
        boolean compareExactly;
        boolean compareCaseSensitive;

        public FrameByTitleChooser(String t, boolean ce, boolean cc) {
            super();
            title = t;
            compareExactly = ce;
            compareCaseSensitive = cc;
        }

        @Override
        public boolean checkComponent(Component comp) {
            if (comp instanceof Frame) {
                if ((FIND_INVISIBLE_WINDOWS || (comp.isShowing() && comp.isVisible()))
                        && ((Frame) comp).getTitle() != null) {
                    String titleToComp = ((Frame) comp).getTitle();
                    String contextToComp = title;
                    if (compareCaseSensitive) {
                        titleToComp = titleToComp.toUpperCase();
                        contextToComp = contextToComp.toUpperCase();
                    }
                    if (compareExactly) {
                        return titleToComp.equals(contextToComp);
                    } else {
                        return titleToComp.contains(contextToComp);
                    }
                }
            }
            return false;
        }

        @Override
        public String getDescription() {
            return title;
        }

        @Override
        public String toString() {
            return "FrameByTitleChooser{" + "title=" + title + ", compareExactly=" + compareExactly + ", compareCaseSensitive=" + compareCaseSensitive + '}';
        }
    }

}