# com.bea.ide.ui.help
HelpSvc Class

public class HelpSvc
extends `Object`

This service is used to find and display context-sensitive help topics from the IDE. In the local case, HelpSvc is also used to integrate new help into the help system's table of contents and search index.

When the IDE is started, `HelpSvc``` constructs a help path consisting of locations where help topics may be found. The help path includes help provided with IDE extensions, help provided with third-party controls and API help such as Javadoc for the J2SE and J2EE APIs.

When F1 is pressed in the IDE, the implementation of `IHelpDriver``` (if any) for the current view is found and `IHelpDriver.getHelpContextList(IElement)``` is invoked (by the shell). `IHelpDriver.getHelpContextList(IElement)``` returns an ordered array of context URNs that indicate the context for which help is being sought.

The list of context URNs is passed to `HelpSvc.I.resolveContextAsync(URI[])```, which attempts to resolve the context URNs against the entries in the help path. If resolution is successful, the topic is displayed in a browser via `HelpSvc.I.displayHelp(URL)```

Context-Sensitive Help

Context-sensitive help is a two step process. When help is desired for the current UI context (typically, when F1 is pressed), the IDE looks for an implementation of `IHelpDriver``` on the current view. The IHelpDriver is invoked and returns an ordered list of context URNs (URNs). Context URNs uniquely identify the entity for which help is desired, such as a Java class, a language keyword, or a JSP tag from a tag library. Once the list of context URNs has been generated, the HelpSvc attempts to resolve the context URNs against a help path - a list of potential help topic locations.

The Help Path

HelpSvc constructs and maintains a help path, which is a list of potential locations for context-sensitive help topics.

The help path consists of the following:

1. paths specified in extension.xml files with URN "urn:com-bea-ide:help", for all extensions
2. paths to help content associated with "external components" (typically controls)
3. arbitrary user-specified help path entries
4. paths to API docs such as J2SE and J2EE Javadoc

The format for a "urn:com-bea-ide:help" entry in extension.xml is:

     <extension-xml id="urn:com-bea-ide:help">
         <help-root [parent="parent"] dir="directory"/>
         <help-root url="url-to-help-root/>
     </extension-xml>

directory | the directory to be searched as a help root. directory is relative to parent and/or url.
parent | a path to a directory relative to the `extension` directory of workshop. an absolute path may be used, but it is not recommended. If ommitted, the directory is assumed to be in the extension's own directory.
url-to-help-root | an absolute URL that specifies a new help root. this may be any url, but will typically be htpp or file based.

A `help-root` may specify both a `url` and a `parent`. When the IDE help mode is "online", `url` will be used. When the help mode is "local", `parent` will be used.

Context URNs

Each context URN is of one of the following forms:

- urn:java-class:<package>[.<package>].package-summary
- urn:java-class:<package>.[<package>.]<className>[#methodName[(<argType>[,<argType>])]]
- urn:taglib:[<tagLibURI>]/<tagName>
- urn:javadoc-tag:[<prefix>.]<tagName>
- urn:keyword:[<language>.]<keywordName>

Some example context URNs are:

- `urn:java-class:com.bea.control.package-summary`
- `urn:java-class:com.bea.control.JwsContext`
- `urn:java-class:com.bea.control.JwsContext#finishConversation`
- `urn:java-class:java.lang.String#substring(int, int)`
- `urn:javadoc-tag:jws.operation`
- `urn:taglib:www.bea.com/workshop/netui-tags-html-1.0/button`
- `urn:keyword:java.while`

An implementation of `IHelpDriver``` generates context URNs that are appropriate for selected items in that view. For example, a Java source editor would generate context URNs appropriate for the current location of the text cursor. This might be a keyword, an annotation (Javadoc tag), a variable (resolving to a class) or a method (also resolving to a class). In the case of a Java class, the list of URNs returned would reflect the inheritance hierarchy of the class, so that the most specific help topic would be found first, followed by less specific topics if the most specific topics do not exist.

Context-Sensitive Help Resolution

The HelpSvc may also be used to resolve a list of context URNs to a URL using the help path. Context URNs are described above.

When `HelpSvc.I.resolveContextAsync(URI[])``` is called with a list of context URNs, the help service attempts to resolve each context URN (converted to a relative URL) against each entry in the help path. If a resolution occurs, the complete URL to the resolved topic (which is "help path URL" + "context URL") is sent to a browser for display.

HelpDrivers

DocumentViews and FrameViews may have an `IHelpDriver```, which will generate context URNs for the current context when context-sensitive (F1) help is requested in that view.

Displaying Help

The HelpSvc provides three mechanisms for displaying help:

1. call `HelpSvc``` with the path to a specific help file, relative to a help path entry. The help service will attempt to resolve the path against the entries in the help path.
2. call `HelpSvc``` with an array of context URN URIs. The help service will attempt to resolve each of the context URNs against each of the help path entries, in order.
3. call `HelpSvc``` with a URL.

Locales and Internationalization The WebLogic Workshop help system is internationalized and will attempt to provide help for the current locale whenever such content is available. This is accomplished by using the placeholder `$locale` in help path entries.

A locale is a 2-letter ISO language code optionally followed by a 2-letter country/region code. The following are examples of locales:

- `en`
- `ja`
- `ja_JP`
- `zh_CN`

When the help system attempts to resolve a URL, it attempts resolution by replacing the `$locale` placeholder with the following values, in order:

1. the value of the system property `workshop.help.locale`
2. the user's complete current locale
3. the language code of the current locale
4. `en`

The user's current locale is obtained by calling `Locale.getDefault()```.

Related Topics

``IHelpDriver``

Hierarchy
  `Object`
  `HelpSvc`

## Nested Class Summary

`public static interface` | `HelpSvc.I` The interface that must be implemented by a help service provider.

## Field Summary

`protected static `HelpSvc.I`` | `instance` HelpSvc.I

## Constructor Summary

HelpSvc()

## Method Summary

`public static `HelpSvc.I`` | `get`() get the single instance of this service.

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

## Field Detail

### instance

    protected static HelpSvc.I instance

## Constructor Detail

### HelpSvc

    public HelpSvc()

## Method Detail

### get() Method

    public static HelpSvc.I get()

get the single instance of this service.