commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-commons-sandbox/resources/src/java/org/apache/commons/resources Resources.java
Date Fri, 27 Dec 2002 21:54:33 GMT
craigmcc    2002/12/27 13:54:33

  Modified:    resources/src/java/org/apache/commons/resources
                        Resources.java
  Log:
  Clean up the Javadocs and formatting of the o.a.c.r.Resources interface.
  Add a (currently commented-out) getObject() method that will support
  retrieval of non-text resource objects directly.  This will be enabled
  once the existing implementations are extended to support it.
  
  Revision  Changes    Path
  1.3       +137 -68   jakarta-commons-sandbox/resources/src/java/org/apache/commons/resources/Resources.java
  
  Index: Resources.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/resources/src/java/org/apache/commons/resources/Resources.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- Resources.java	24 Oct 2001 20:46:03 -0000	1.2
  +++ Resources.java	27 Dec 2002 21:54:32 -0000	1.3
  @@ -7,7 +7,7 @@
    *
    * The Apache Software License, Version 1.1
    *
  - * Copyright (c) 1999-2001 The Apache Software Foundation.  All rights
  + * Copyright (c) 1999-2002 The Apache Software Foundation.  All rights
    * reserved.
    *
    * Redistribution and use in source and binary forms, with or without
  @@ -59,117 +59,186 @@
    *
    */
   
  -
   package org.apache.commons.resources;
   
  -import java.util.Locale;
  -import java.util.TimeZone;
  -import java.util.MissingResourceException;
   
  -import java.io.Reader;
   import java.io.InputStream;
  +import java.io.Reader;
   import java.io.Serializable;
  -
   import java.net.URL;
  +import java.util.Locale;
  +import java.util.TimeZone;
  +
   
   /**
  - * This class represents an internationalized resource, that is, anything
  - * that can pull specific content out in the context of a certain locale and
  - * optionally time zone.  The basic idea is that each peice of content is
  - * associated with a String key, and that key is used to retrieve the content.
  - * Developers using implementations of this class should keep in mind that
  - * they should use the getInputStream method that returns an InputStream and write
  - * directly to the Stream they're using for resources that contain large size
  - * content.<br />
  - * Developers implementing resources should extend the
  - * {@link org.apache.commons.resources.ResourcesBase ResourcesBase}
  - * class and override the necessary methods to shield themselves from any
  - * changes that may occur in this interface.
  + * <p>An abstract representation of a set of internationalized resources,
  + * which are arbitrary objects identified by a unique String <code>key</code>.
  + * Localized versions of the resources (based on Locale and optional
  + * TimeZone parameters) can be retrieved in a variety of formats.</p>
  + *
  + * <p>Different implementations of the {@link Resources} interface support
  + * a variety of mechanisms for acquiring the data content represented by
  + * the keys.  Examples could include property files, XML files, databases, web
  + * application resources, and other specialized approaches as desired.</p>
  + *
  + * <p>Different implementations of the {@link Resources} interface may apply
  + * different semantics to the use of the <code>locale</code> and/or
  + * <code>timeZone</code> attributes used to perform localization.  Consult
  + * the documentation for the specific {@link Resources} implementation you
  + * are using for the specific details of your implementation.</p>
  + *
  + * <p>Developers implementing {@link Resources} should extend the
  + * {@link ResourcesBase} class, and override the necessary methods,
  + * to shield themselves from future changes that may occur in this interface.
  + *
    * @author Mike Schachter (mschachter@hp.com)
  + * @author Craig R. McClanahan
    * @version $Revision$ $Date$
    */
  +
   public interface Resources extends Serializable {
   
   
  +    // ------------------------------------------------------ Lifecycle Methods
  +
  +
       /**
  -     * This is called on to initialize the Resources, before any of the
  -     * get* methods are called.
  +     * <p>This must be called to initialize the data content of this
  +     * {@link Resources} instance, before any of the <code>getXxx()</code>
  +     * methods are called.</p>
  +     *
  +     * @exception ResourcesException if an error occurs during initialization
        */
       public void init() throws ResourcesException;
   
  +
       /**
  -     * This method is called when the manager of this resource decides that
  -     * it's no longer needed.
  +     * <p>This method must be called when the manager of this resource
  +     * decides that it's no longer needed.  After this method is called,
  +     * no further calls to any of the <code>getXxx()</code> methods are
  +     * allowed.</p>
  +     *
  +     * @exception ResourcesException if an error occurs during finalization
        */
       public void destroy() throws ResourcesException;
   
  +
  +    // ----------------------------------------------- Resources Naming Methods
  +
  +
       /**
  -     * Get the name of this resource
  -     * @return A logical String representation of the name of this resource
  +     * <p>Return the name of this resource.</p>
        */
       public String getName();
   
  +
       /**
  -     * Set the name of this resource
  +     * <p>Set the name of this resource.  This method should only be called
  +     * by the {@link ResourcesFactory} that is creating new instances.</p>
  +     *
        * @param name A logical String representation of the name of this resource
        */
       public void setName(String name);
   
  +
  +    // ---------------------------------------------- Content Retrieval Methods
  +
  +
       /**
  -     * Retrieves content based on the locale and time zone specified.  Note
  -     * that this method has the potential to cause memory problems for content
  -     * that is relatively large.
  -     * @param key The key for the content
  -     * @param locale The locale to retreive the content in, if <code>null</code>,
  -     *               the default locale
  -     * @param timeZone The time zone to retrieve the content for, if <code>null</code>,
  -     *                 the default time zone.  Resources implementations may ignore
  -     *                 the time zone argument all together.
  +     * <p>Return the content for the specified <code>key</code> as a
  +     * byte array, localized based on the specified <code>locale</code>
  +     * and/or <code>timeZone</code>.</p>
  +     *
  +     * @param key Identifier for the requested content
  +     * @param locale Locale with which to localize retrieval,
  +     *  or <code>null</code> for the default Locale
  +     * @param timeZone TimeZone with which to localize retrieval,
  +     *  or <code>null</code> for the default TimeZone
  +     *
  +     * @exception ResourcesException if an error occurs retrieving or
  +     *  returning the requested content
        */
       public byte[] getBytes(String key, Locale locale, TimeZone timeZone)
           throws ResourcesException;
   
  +
       /**
  -     * Retrieves content based on the locale and time zone specified.  Note
  -     * that this method has the potential to cause memory problems for content
  -     * that is relatively large.
  -     * @param key The key for the content
  -     * @param locale The locale to retreive the content in, if <code>null</code>,
  -     *               the default locale
  -     * @param timeZone The time zone to retrieve the content for, if <code>null</code>,
  -     *                 the default time zone.  Resources implementations may ignore
  -     *                 the time zone argument.
  -     * @return A String representing the data specified by key.  The encoding
  -     *         of the String is implementation dependent.
  +     * <p>Return the content for the specified <code>key</code> as an
  +     * InputStream, localized based on the specified <code>locale</code>
  +     * and/or <code>timeZone</code>.</p>
  +     *
  +     * @param key Identifier for the requested content
  +     * @param locale Locale with which to localize retrieval,
  +     *  or <code>null</code> for the default Locale
  +     * @param timeZone TimeZone with which to localize retrieval,
  +     *  or <code>null</code> for the default TimeZone
  +     *
  +     * @exception ResourcesException if an error occurs retrieving or
  +     *  returning the requested content
        */
  -    public String getString(String key, Locale locale, TimeZone timeZone)
  +    public InputStream getInputStream(String key, Locale locale,
  +                                      TimeZone timeZone)
           throws ResourcesException;
   
  +
       /**
  -     * Retrieves an InputStream representing the content based on the key, locale,
  -     * and time zone specified
  -     * @param key The key for the content
  -     * @param locale The locale to retreive the content in, if <code>null</code>,
  -     *               the default locale
  -     * @param timeZone The time zone to retrieve the content for, if <code>null</code>,
  -     *                 the default time zone.  Resources implementations may ignore
  -     *                 the time zone argument all together.
  +     * <p>Return the content for the specified <code>key</code> as an
  +     * Object, localized based on the specified <code>locale</code>
  +     * and/or <code>timeZone</code>.</p>
  +     *
  +     * @param key Identifier for the requested content
  +     * @param locale Locale with which to localize retrieval,
  +     *  or <code>null</code> for the default Locale
  +     * @param timeZone TimeZone with which to localize retrieval,
  +     *  or <code>null</code> for the default TimeZone
  +     *
  +     * @exception ResourcesException if an error occurs retrieving or
  +     *  returning the requested content
        */
  -    public InputStream getInputStream(String key, Locale locale, TimeZone timeZone)
  +    /* FIXME -- Comment out until implementations are extended to support it
  +    public Object getObject(String key, Locale locale, TimeZone timeZone)
           throws ResourcesException;
  +    */
  +
   
       /**
  -     * Retrieves a Reader representing the content based on the key, locale,
  -     * and time zone specified
  -     * @param key The key for the content
  -     * @param locale The locale to retreive the content in, if <code>null</code>,
  -     *               the default locale
  -     * @param timeZone The time zone to retrieve the content for, if <code>null</code>,
  -     *                 the default time zone.  Resources implementations may ignore
  -     *                 the time zone argument all together.
  +     * <p>Return the content for the specified <code>key</code> as a
  +     * Reader, localized based on the specified <code>locale</code>
  +     * and/or <code>timeZone</code>.</p>
  +     *
  +     * @param key Identifier for the requested content
  +     * @param locale Locale with which to localize retrieval,
  +     *  or <code>null</code> for the default Locale
  +     * @param timeZone TimeZone with which to localize retrieval,
  +     *  or <code>null</code> for the default TimeZone
  +     *
  +     * @exception ResourcesException if an error occurs retrieving or
  +     *  returning the requested content
        */
       public Reader getReader(String key, Locale locale, TimeZone timeZone)
           throws ResourcesException;
  +
  +
  +    /**
  +     * <p>Return the content for the specified <code>key</code> as a
  +     * String, localized based on the specified <code>locale</code>
  +     * and/or <code>timeZone</code>.</p>
  +     *
  +     * @param key Identifier for the requested content
  +     * @param locale Locale with which to localize retrieval,
  +     *  or <code>null</code> for the default Locale
  +     * @param timeZone TimeZone with which to localize retrieval,
  +     *  or <code>null</code> for the default TimeZone
  +     *
  +     * @exception ResourcesException if an error occurs retrieving or
  +     *  returning the requested content
  +     */
  +    public String getString(String key, Locale locale, TimeZone timeZone)
  +        throws ResourcesException;
  +
  +
  +
  +
   }
   
   
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message