You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by cr...@apache.org on 2002/12/27 22:54:33 UTC
cvs commit: jakarta-commons-sandbox/resources/src/java/org/apache/commons/resources Resources.java
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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>