GetText (SAFS API DOCUMENT)

java.lang.Object
- org.safs.GetText

All Implemented Interfaces:

java.io.Serializable
```
public class GetText
extends java.lang.Object
implements java.io.Serializable
```
Purpose: GetText, get text from a resource bundle
Lifetime: must be instantiated before it can be used
NOTE, the documentation below are thoughts, and are not in-totale implemented here.
We are discussing a new STAF service (initially a Java Class that can then point to a service) to provide string resources. The intent is multi-purpose. The initial driving force was to have a service that would provide consistent log messages regardless of which engine was in use. In other words, all the engines would get the text to be logged from the service so that their messages would be the same. Right now, RobotJ and Robot Classic messages for the same item are very different. Future engines could just inherit the message pool we will have in place via this service.
This will also provide the opportunity for engine messages in different languages, and to provide localized string support for NLS testing of the target application. Test data like string benchmark values for Caption or visible text could be stored in different files based on locale.
Some thoughts:
1) It is important to remember that our logging API takes both a message and a detailed description. (It still does, right?) So all of this detailed failure info need not be in the "message" part of the logged message. Indeed, as we should see by reviewing much of the Robot Classic logging, the details of which table, which line, and sometimes even the inputrecord string itself are often logged in the detailed description, and not in the main message itself.
2) The "failure" and "passed" messages are not to be handled differently, or by some type of different code. We are just requesting a named string that may (or may not) take parameters.
MyMessage :A message taking %1% parameters for reasons of %2% and %3%.
3) Parameters should be reusable in the same message and do not have to be used in passed order.
MyMsg :A %3% message taking %1% parameters for reasons of %3%, but not %2%.
4) Each message independently determines how many arguments it accepts. What do we do when insufficient arguments are provided? "" ?
Output=A message taking 3 parameters for reasons of , but not insanity.
5) What do we do when additional arguments are provided beyond those needed by the message? Append to the end of the message?
6) The Java Class API must be allowed to accept an optional LOCALE parameter for the call. LOCALE parameter specifications and derived filename specifications should conform to the industry standard (en, fr, de, etc..) Without the optional parameter, the current (or preset?) LOCALE should be used by default.
7) "failure" messages (or their description messages) should try to include the test table filename in addition to the line number in that test table that failed. The "line number" in the example is not for the line number in the CF library, but for the test table that is being executed.
Output="...failed at line 6 in \LoginUser.sdd" (we may choose to not output info.)
8) The Java Class API needs to be able to handle multiple named file sources. We need to be able to request strings not only for the log messages, but for the test data, or any number of other sources. Much like we are able to open multiple App Maps.
9) Like SAFSMAPS and SAFSVARS, we need to be able to programmatically clear any stored cache. We don't want to have to shutdown the service(Class), STAF, or RobotJ to force newly edited content to be loaded.

Since:

NOV 05, 2003
NOV 06, 2003 (DBauman) Original Release
NOV 08, 2003 (Carl Nagle) Removed thrown exceptions
NOV 09, 2003 (Carl Nagle) Fixed problem with altext duplicated in return when MissingResource encountered. Other Exception code, also.

Author:

Doug Bauman

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`(package private) java.lang.String`	`delim` delimter (currently %) used to 'convert' text with parameters as in %1% or %2%
`protected java.util.ResourceBundle`	`textResources` this field is loaded by the 'loadResource' method using the 'bundleName', Locale.getDefault() and ClassLoader.getSystemClassLoader()

Constructor Summary

Constructors
Constructor and Description
`GetText()` no-arg constructor for javabeans
`GetText(java.lang.String prefixBundleName, java.util.Locale locale)` Purpose: constructor; assigns the prefixBundleName and the locale and loads the resource.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.String`	`convert(java.lang.String key, java.lang.String alttext, java.util.Collection params)` Purpose: Convert text using supplied parameters in a 'text' message, specified by: %num%, where num starts from 1; parameters should be reusable in the same message and do not have to be used in passed order.
`java.lang.String`	`convert(java.lang.String text, java.lang.String alttext, java.lang.String p1)` Purpose: convenience function to build a Collection with params Assumptions: calls 'convert(text, Collection of params)'
`java.lang.String`	`convert(java.lang.String text, java.lang.String alttext, java.lang.String p1, java.lang.String p2)` Purpose: convenience function to build a Collection with params Assumptions: calls 'convert(text, Collection of params)'
`java.lang.String`	`convert(java.lang.String text, java.lang.String alttext, java.lang.String p1, java.lang.String p2, java.lang.String p3)` Purpose: convenience function to build a Collection with params Assumptions: calls 'convert(text, Collection of params)'
`java.lang.String`	`convert(java.lang.String text, java.lang.String alttext, java.lang.String p1, java.lang.String p2, java.lang.String p3, java.lang.String p4)` Purpose: convenience function to build a Collection with params Assumptions: calls 'convert(text, Collection of params)'
`java.lang.String`	`convert(java.lang.String text, java.lang.String alttext, java.lang.String p1, java.lang.String p2, java.lang.String p3, java.lang.String p4, java.lang.String p5)` Purpose: convenience function to build a Collection with params Assumptions: calls 'convert(text, Collection of params)'
`java.lang.String`	`getBundleName()`
`java.util.Locale`	`getLocale()`
`protected java.lang.String`	`getParam(int num, java.util.Collection params)` Purpose: grab a param from a Collection, if not there, append (unknown); it will also attempt to 'translate' the value obtained before returning it, using the same resource file, if it cannot translate, then it just returns the parameter at the position.
`java.lang.String`	`getPrefixBundleName()`
`void`	`loadResource()` Purpose: load the resource defined in 'bundleName' Side Effects: 'textResources' State Read: 'bundleName' NOTE: the ".properties" is assumed by the 'ResourceBundle.getBundle' method
`static void`	`main(java.lang.String[] args)` used to test
`protected void`	`setBundleName()` set bundle name using prefixBundleName and specified Locale
`void`	`setLocale(java.util.Locale locale)`
`void`	`setPrefixBundleName(java.lang.String prefixBundleName)`
`java.lang.String`	`text(java.lang.String resourceKey)` Purpose: get the text from the resource bundle State Read: textResources.getString(resourceKey) Assumptions: resource bundle is lazily loaded if not already loaded
`java.lang.String`	`text(java.lang.String resourceKey, java.lang.String alternateText)` Purpose: get the text from the resource bundle, if not found, then return the 'alternateText' State Read: textResources.getString(resourceKey) Assumptions: resource bundle is lazily loaded if not already loaded
`java.lang.String`	`translate(java.lang.String resourceKey)` Purpose: get the text from the resource bundle, but if not found, return key State Read: textResources.getString(resourceKey) Assumptions: resource bundle is lazily loaded if not already loaded

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - delim
```
java.lang.String delim
```
    delimter (currently %) used to 'convert' text with parameters as in %1% or %2%
  - textResources
```
protected java.util.ResourceBundle textResources
```
    this field is loaded by the 'loadResource' method using the 'bundleName', Locale.getDefault() and ClassLoader.getSystemClassLoader()
- Constructor Detail
  - GetText
```
public GetText()
```
    no-arg constructor for javabeans
  - GetText
```
public GetText(java.lang.String prefixBundleName,
               java.util.Locale locale)
```
    Purpose: constructor; assigns the prefixBundleName and the locale and loads the resource.
    
    Parameters:
    
    prefixBundleName, - String
- Method Detail
  - getLocale
```
public java.util.Locale getLocale()
```
  - setLocale
```
public void setLocale(java.util.Locale locale)
```
  - getPrefixBundleName
```
public java.lang.String getPrefixBundleName()
```
  - setPrefixBundleName
```
public void setPrefixBundleName(java.lang.String prefixBundleName)
```
  - getBundleName
```
public java.lang.String getBundleName()
```
  - setBundleName
```
protected void setBundleName()
```
    set bundle name using prefixBundleName and specified Locale
  - loadResource
```
public void loadResource()
                  throws java.util.MissingResourceException
```
    Purpose: load the resource defined in 'bundleName'
    Side Effects: 'textResources'
    State Read: 'bundleName'
    NOTE: the ".properties" is assumed by the 'ResourceBundle.getBundle' method
    
    Throws:
    
    java.util.MissingResourceException
  - text
```
public java.lang.String text(java.lang.String resourceKey,
                             java.lang.String alternateText)
```
    Purpose: get the text from the resource bundle, if not found, then return the 'alternateText'
    State Read: textResources.getString(resourceKey)
    Assumptions: resource bundle is lazily loaded if not already loaded
    
    Parameters:
    
    resourceKey, - String
    
    alternateText, - String
    
    Returns:
    
    String
  - text
```
public java.lang.String text(java.lang.String resourceKey)
                      throws java.util.MissingResourceException
```
    Purpose: get the text from the resource bundle
    State Read: textResources.getString(resourceKey)
    Assumptions: resource bundle is lazily loaded if not already loaded
    
    Parameters:
    
    resourceKey, - String
    
    Returns:
    
    String
    
    Throws:
    
    java.util.MissingResourceException
  - translate
```
public java.lang.String translate(java.lang.String resourceKey)
```
    Purpose: get the text from the resource bundle, but if not found, return key
    State Read: textResources.getString(resourceKey)
    Assumptions: resource bundle is lazily loaded if not already loaded
    
    Parameters:
    
    resourceKey, - String
    
    Returns:
    
    String, translated, but if not found, return the key
  - convert
```
public java.lang.String convert(java.lang.String key,
                                java.lang.String alttext,
                                java.util.Collection params)
```
    Purpose: Convert text using supplied parameters in a 'text' message, specified by: %num%, where num starts from 1; parameters should be reusable in the same message and do not have to be used in passed order. for example:
```
    MyMsg  :A %3% message taking %1% parameters for reasons of %3%, but not %2%.
 
```
    would return, using parameters : (3, triviality, fun)
```
    MyMsg  :A fun message taking 3 parameters for reasons of fun, but not triviality.
 
```
    Assumptions: any additional parameters are appended at the end with commas; if there are not enough params, then (unknown) is inserted instead.
    Parameters:
    
    text, - String with embedded %1% style paramenter tags
    
    altText, - String
    
    params, - Collection of parameters
    
    Returns:
    
    String
  - convert
```
public java.lang.String convert(java.lang.String text,
                                java.lang.String alttext,
                                java.lang.String p1)
```
    Purpose: convenience function to build a Collection with params
    Assumptions: calls 'convert(text, Collection of params)'
  - convert
```
public java.lang.String convert(java.lang.String text,
                                java.lang.String alttext,
                                java.lang.String p1,
                                java.lang.String p2)
```
    Purpose: convenience function to build a Collection with params
    Assumptions: calls 'convert(text, Collection of params)'
  - convert
```
public java.lang.String convert(java.lang.String text,
                                java.lang.String alttext,
                                java.lang.String p1,
                                java.lang.String p2,
                                java.lang.String p3)
```
    Purpose: convenience function to build a Collection with params
    Assumptions: calls 'convert(text, Collection of params)'
  - convert
```
public java.lang.String convert(java.lang.String text,
                                java.lang.String alttext,
                                java.lang.String p1,
                                java.lang.String p2,
                                java.lang.String p3,
                                java.lang.String p4)
```
    Purpose: convenience function to build a Collection with params
    Assumptions: calls 'convert(text, Collection of params)'
  - convert
```
public java.lang.String convert(java.lang.String text,
                                java.lang.String alttext,
                                java.lang.String p1,
                                java.lang.String p2,
                                java.lang.String p3,
                                java.lang.String p4,
                                java.lang.String p5)
```
    Purpose: convenience function to build a Collection with params
    Assumptions: calls 'convert(text, Collection of params)'
  - getParam
```
protected java.lang.String getParam(int num,
                                    java.util.Collection params)
```
    Purpose: grab a param from a Collection, if not there, append (unknown); it will also attempt to 'translate' the value obtained before returning it, using the same resource file, if it cannot translate, then it just returns the parameter at the position. If a param is null then "(null)" will be returned.
    
    Parameters:
    
    num, - int, starting from 1
    
    params, - Collection
    
    Returns:
    
    String, if not found in 'params' then "(unknown)" is found
  - main
```
public static void main(java.lang.String[] args)
```
    used to test

Class GetText

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

delim

textResources

Constructor Detail

GetText

GetText

Method Detail

getLocale

setLocale

getPrefixBundleName

setPrefixBundleName

getBundleName

setBundleName

loadResource

text

text

translate

convert

convert

convert

convert

convert

convert

getParam

main