• Home
• Demonstration
• Download
• Component Gallery
• Application Gallery
• FAQ
• News
• Javadoc
• Bugs
• Echo Developer Forums
• Mailing List
• CVS
• SourceForge

This FAQ is growing out of questions posted to the EchoPoint and Echo mailing lists.  It contains code snippets to help make things more clear.

 

Q. I downloaded the EchoPoint code and  created a valid Echo application but it does not seem to work?

You need to make sure you "register" the components within the Echo framework.  The Echo components are registered by default however 3rd party components, such as EchoPoint, must be registered.  The following code snippet is the easiest way to register the EchoPoint components.

public class EchoPointTest extends nextapp.echoservlet.EchoServer {
    static {
        echopoint.ui.Installer.register();
    }
}

The other way to register a component is via its individual class name as in

echopoint.ui.Installer.register(DatePicker.class);

However in general you can just register all the EchoPoints components at once.

 

Q. How do I access the ServletConfig object so I can get deployment parameters within my application?

A. The nextapp.echo.EchoInstance class stores a ServerContext object in an internal attribute map.  This object encapsulates a number of application properties, including the servlet ServletConfig object.

You can get it using the following code.:

ServerContext serverContext = (ServerContext) echoInstance.getAttribute(ServerContext.ATTRIBUTE_NAME);
ServletConfig servletConfig = serverContext.getServletConfig();

Q. How do I set the character encoding within an Echo application?

A. Again this is related to the provided nextapp.echoserver.ServerContext object.

You can use the following code :

ServerContext serverContext = (ServerContext) getAttribute(ServerContext.ATTRIBUTE_NAME);
serverContext.setCharacterEncoding(EchoServer.CHARACTER_ENCODING_ISO_8859_1);

Echo has the following defined strings for character encoding

    public static final String CHARACTER_ENCODING_ISO_8859_1 = "iso-8859-1";
    public static final String CHARACTER_ENCODING_ISO_8859_2 = "iso-8859-2";
    public static final String CHARACTER_ENCODING_ISO_8859_3 = "iso-8859-3";
    public static final String CHARACTER_ENCODING_ISO_8859_4 = "iso-8859-4";
    public static final String CHARACTER_ENCODING_ISO_8859_5 = "iso-8859-5";
    public static final String CHARACTER_ENCODING_US_ASCII = "us-ascii";
    public static final String CHARACTER_ENCODING_UTF_8 = "utf-8";

You can use your own strings if need be for example :

serverContext.setCharacterEncoding("GBK");

Q. How do I get access to the HttpSession object, just like in a normal servlet application?

A. Again this is related to the provided ServerContext object. In fact it has a number of methods that give you access to the "normal" servlet objects such as HttpSession.

The key methods are :

public ServletConfig getServletConfig();
public HttpSession getSession();
public Principal getUserPrincipal();
public boolean isUserInRole(String role);
public String getCharacterEncoding();

Q. How do I set cookies within an Echo application?

A. Again this is related to the provided ServerContext object. It has a getCookieManager() method that returns an object that allows you to retrieve and set javax.servlet.http.Cookie objects. 

One thing to consider in your design when using cookies it that Echo provides an EchoInstance object for every Servlet session started for an end user.  This EchoInstance is stored in the session.  Therefore you don't really need to use the HttpSession object to store end user information in.  You can simple add member variables to the EchoInstance class (or any other class contained within it) and store end user information there.

However to store "long term" end user information about a user, for example their preferred Locale(), then "persistent" Cookies are a good way of achieving this.

 Q. Does Echo have file upload and/or download functionality?

A. Yes it does.  An optional library call the File Transfer library is available.  It allows files to be uploaded via the usual browser multipart message transfer mechanism.  The library can be found at :

http://www.nextapp.com/products/echo/components/catalog

The FileUpload component can be used within an Echo application to provide a mechanism for users to upload files.   The file contents are captured and an UploadHandler implementation is notified of the file upload via an UploadEvent object.  This UploadEvent contains the content type of the file, its size and an input stream containing its data.

class BasicUploadTestApp extends EchoInstance implements UploadHandler {
        .......
        .......

    public void fileUpload(UploadEvent e) {
        content.add(Filler.createVerticalStrut(0));
        content.add(new Label("Fileup: size=" + e.getSize()));
    }

    public void invalidFileUpload(UploadEvent e) {
         content.add(new Label("file uploaded, size=" + e.getSize()));
    }

    public Window init() {
        .......
        UploadSelect uploadSelect = new UploadSelect();
        uploadSelect.setBackground(new Color(0xdfdfdf));
        uploadSelect.setForeground(Color.BLACK);
        uploadSelect.setUploadHandler(this);
        .......
     }
}

A Download component is provided for the opposite functionality.  It allows a file to downloaded to a client browser.  A file will be downloaded if the Download component is set to active via the setActive() method.

A DownloadProvider implementation is required to source the file content type, file name, file size and to write the contents of the file to an output stream.

The use of an interface allows you to provide your own DownloadProvider implementation and perhaps source a file's content from a place other than the file system, such as a database.

class TestDownloadProvider implements DownloadProvider {
        private FileInfo file = null;

        public TestDownloadProvider(FileInfo file) {
            super();
            this.file = file;
        }

        public String getContentType() {
            return file.contentType;
        }

        public String getFileName() {
            if (setFileName.isSelected()) {
                return file.fileName;
            } else {
                return null;
            }
        }

        public int getSize() {
            return -1;
        }

        public void writeFile(OutputStream out) {
            byte[] buffer = new byte[4096];
            int bytesRead = 0;
            InputStream in = null;

            try {
                in = TestDownloadProvider.class.getResourceAsStream("/testresource/" + file.fileName);
                do {
                    bytesRead = in.read(buffer);
                    if (bytesRead > 0) {
                        out.write(buffer, 0, bytesRead);
                    }
                } while (bytesRead > 0);
            } catch (IOException ex) {
                throw new IllegalArgumentException("Cannot get resource: \"" + file.fileName + "\": " + ex);
            } finally {
                if (in != null) { try { in.close(); } catch (IOException ex) { } }
            }
        }

Q. How do I put Tool Tips on my Echo and EchoPoint components?

A. A new nextapp.echo.ToolTipSupport interface has been added to allow Components to provide tool tips.  Virtually all of the Echo and EchoPoint components now implement this interface.  You can call it as follows :

TextField textField = new TextField();
textField.setToolTipText("My Tool Tip");

PushButton pushButton =  new PushButton();
pushButton.setToolTipText("Press me quickly!");

Q. How do I do internationlization with Echo and EchoPoint?

A. The nextapp.echo.EchoInstance and nextapp.echo.Component class has a getLocale()/setLocale() property.  This is "inherited" down to contained components.  That is to say, if you call getLocale() on a component, and it has not be set, it will navigate up the component tree to find a Locale() object.

The locale property in EchoInstance is set at application startup based on your visitor's web browser's character encoding. Other than that, Echo relies on Java's built-in I18N/L10N API. For more information look at this Java Tutorial topic:

http://java.sun.com/docs/books/tutorial/i18n/index.html

 

 Q. Does the fact that applications using the Echo framework must extend EchoServer and EchoInstance make such applications derivitives of Echo, requiring source to be made available, even under the LGPL?

A. No.  Applications built using Echo and EchoPoint are NOT required to be licensed under the LGPL.

You may license Echo applications you create using whatever license you want to. It's entirely legal to create closed-source proprietary apps using Echo. It's also legal to distribute Echo binaries with your product.

The LGPL only requires that if you modify Echo itself, that you make your changes to the framework itself available in source form to others.

Q. How do I make my application refresh itself without user interaction?  Can I use a META refresh tag?

A. EchoPoint has a non visual Timer class, that accepts a timeout in milliseconds.  When placed within an Echo application it will automatically create an ActionEvent back on the server when it times out.  From there you can update the application state or models etc.. and the Echo will reflect all changes back on the end users browser.

Timer t = new Timer(10000);
t.setActionCommand("timerFired");
t.addActionListener(this);
t.start();

You can only have one effective Timer on a Window at a time. This is because once the lowest delay timer has popped, any screen updates will cause all Timers on that Window to be reset to their respective starting delays, regardless of how much time has passed since the last event happened on any given timer.

Note that this is a very coarse timer. The timer is run on the client and the timeout must travel back to the server before any other code can be notified of this event. Therefore the granuality of the timer cannot be gaurunteed, as it depends on the client speed and the network speed between the client and server.

 

Q. Does Echo / EchoPoint have built in data validation?

A. No they dont.  Echo and EchoPoint dont not have any formal code interfaces for data validation.  You should so it back at the server when an ActionEvent is raised, such as a Button press.  How you validate your data is completely up to you.

 

Q. But nextapp.echo.Component has a validate method.  Isnt that valiudation?

A. No.  This method is called just before an Component is to be redrawn.  It allows the Component to update (or validate) its internal state before its UI peer draws its representation.  This allows it to optimize its rendering by delaying property updates until the final moment.

For example the Tachometer component does not redrawn its graphical representation until the validate() method is called.  This allows a number of property updates to occur without incurring the overhead of drawing the graphical image over and over.

 

Q. How can I name my Components?

A. nextapp.echo.Component has a getIdentifier()/setIdentifier() property that you can use. This property is an Object you like.  In most cases it would be a String object, but you can set it to any object at all.

 

Q. How can I change the apprearance of my Echo Application without making Java code changes?

A. EchoPoint has a 'CSS like' style sheet capability that allows appearance related properties to be set by changing external files.  It is built on top of the Echo Style class which each Component can use.

You can find much more detailed information about style sheets here.

 

Q. How can I link to another web page or servlet?

A. If you want to redirect the browser out of an Echo application, you'll want to make the Application "suspend" itself and redirect to a different URI.

An example of this is available in the TestForEcho program, specifically in the file

"nextapp_echo/src/testforecho/java/nextapp/testforecho/TerminationTest.java".

The Echo application's state will be preserved (until the session times out) and if the user returns the Echo app's URI, the app will reappear in the same state it was in immediately prior to suspending.

EchoPoint has an ExitButton component that makes it easier to provide a link to an outside web URL.  You would create it as follows :

ExitButton exitButton = new ExitButton(getEchoInstance(), "http://echopoint.sf.net", "Click here to go there");
exitButton.setExitMode(false);

This will code will suspend the application state until the user returns or the session timesout.  If a user returns within the session timeout period then all the application state will be exactly as it was.

However if you had :

ExitButton exitButton = new ExitButton(getEchoInstance(), "http://echopoint.sf.net,", "Click here to go there");
exitButton.setExitMode(true);

Then the application will "exit" and all application state will be lost.  If the user returns, the application will go throught the normal application startup routine.

 

Q. Can I customize the Echo application startup routine?

A. Yes you can.  You can have a properties file with the same name and in the same directory as your derived EchoServer class that contains information about the application startup.  So if you have a MyEchoServer class then you will need a MyEchoServer.properties file.

This file has a number of properties you can set that affect application startup.  If you don't provide your own file, the a default one is provided in the Echo library called EchoServer.properties.  It is detailed below.

The configurable properties are :

# Title of the window while the application is starting.
startupWindowTitle                      Application starting...

# Text that will be displayed in the center of the page while the application
# is starting.  This text will only appear if a splash screen is not set.
startupWindowText                       [ please wait ]

# Text displayed when JavaScript is found not to be enabled on the client
# browser.
startupNoScriptErrorText                Your browser either does not support JavaScript or JavaScript is disabled.  This application requires a JavaScript-enabled browser to function properly.


# Delay time before starting application.  A value of 0 (the default)
# indicates that the application should start immediately.  A value of -1
# indicates that the application should wait until the splash scren HTML page
# invokes a JavaScript call to its parent frame's E_start() method.  A positive
# integer value indicates the number of milleseconds to delay before starting.
startupDelay                            0

# When set, the specified splash screen will be displayed when the application
# is starting.
#splashScreenUri                         splash.html

Using this properties file you could provide your own flashy startup screen that displays itself for a number of seconds.

 

Q. How can I put a message box up on the client browser? Can I do this in JavaScript?

A. EchoPoint has a ConfirmButton component that will "prompt" a user with an OK/Cancel question.  If they press OK then the button action command will proceed and possibly raise an event on the server.  If they press Cancel, then nothing will happen.

ConfirmButton confirmButton = new ConfirmButton("Do you want to delete this record?");
confirmButton.addActionListener(this);

 

Q. I have a button in my application but when I press it nothing happens?

A. The button must haver an ActionListener attached to it in order for it to raise and event.  Echo has a speed optimisation so that buttons without ActionListeners attached never generate server side events.  The reasoning behind this is that components with no one listening really dont have an thing interesting to say.

You can add an action listener like so :

button = new Button("My Connected Button");
button.addActionListener(
   new ActionListener() {
      public void actionPerformed(ActionEvent event) {
        // what now brown cow
        button.setText("Pressed");
      }
   }
);