001: /*******************************************************************************
002: * Copyright (c) 2006, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.statushandlers;
011:
012: import java.util.Map;
013:
014: import org.eclipse.ui.application.WorkbenchAdvisor;
015:
016: /**
017: * <p>
018: * Status handlers are part of the status handling facility. The facility is
019: * responsible for handling errors and other important issues in Eclipse based
020: * applications. The handlers are responsible for presenting this errors by
021: * logging or showing error dialogs.
022: * </p>
023: *
024: * <p>
025: * All status handlers extends
026: * <code>org.eclipse.ui.statushandlers.AbstractStatusHandler</code>. Each
027: * handler implements <code>handle(StatusAdapter status, int style)</code>.
028: * This method handles statuses due to handling style. The style indicates how
029: * status handler should handle a status.
030: * </p>
031: *
032: * <p>
033: * For acceptable styles check {@link StatusManager}.
034: * </p>
035: *
036: * <p>
037: * Handlers shoudn't be used directly but through the {@link StatusManager}. It
038: * chooses which handler should be used for handling. There are two ways for
039: * adding handlers to the handling flow. First using extension point
040: * <code>org.eclipse.ui.statusHandlers</code>, second by the workbench
041: * advisor and its method {@link WorkbenchAdvisor#getWorkbenchErrorHandler()}.
042: * If a handler is associated with a product, it is used instead of this defined
043: * in advisor.
044: * </p>
045: *
046: * <p>
047: * A status handler has the id and a set of parameters. The handler can use them
048: * during handling. If the handler is added as an extension, both are set during
049: * initialization of the handler using elements and attributes of
050: * <code>statusHandler</code> element.
051: * </p>
052: *
053: * @since 3.3
054: */
055: public abstract class AbstractStatusHandler {
056:
057: private Map params;
058:
059: private String id;
060:
061: /**
062: * Handles {@link StatusAdapter} objects based on the set style.
063: *
064: * @param statusAdapter
065: * the status adapter. May not be <code>null</code>.
066: * @param style
067: * style constant. Acceptable values are defined in
068: * {@link StatusManager} and can be combined with logical OR.
069: *
070: * @see StatusManager#BLOCK
071: * @see StatusManager#NONE
072: * @see StatusManager#SHOW
073: * @see StatusManager#LOG
074: */
075: public abstract void handle(StatusAdapter statusAdapter, int style);
076:
077: /**
078: * Returns all parameters of the handler.
079: *
080: * @return the parameters
081: */
082: public Map getParams() {
083: return params;
084: }
085:
086: /**
087: * Returns the value of the handler's parameter identified by the given key,
088: * or <code>null</code> if this handler has no such parameter.
089: *
090: * @param key
091: * the name of the property
092: * @return the value of the parameter, or <code>null</code> if this
093: * handler has no such parameter
094: */
095: public Object getParam(Object key) {
096: if (params != null) {
097: return params.get(key);
098: }
099:
100: return null;
101: }
102:
103: /**
104: * Sets the parameters for the handler. If the handler is added via the
105: * <code> org.eclipse.ui.statushandlers extension</code>, the parameters are set
106: * during initialization of the handler using <code>parameter</code>
107: * elements from <code>statusHandler</code>
108: * element.
109: *
110: * @param params
111: * the parameters to set
112: */
113: public void setParams(Map params) {
114: this .params = params;
115: }
116:
117: /**
118: * Returns the id of the handler.
119: *
120: * @return the id
121: */
122: public String getId() {
123: return id;
124: }
125:
126: /**
127: * Sets the id for the handler. If the handler is added as an extension, the
128: * id is set during initialization of the handler using <code>id</code>
129: * attribute of <code>statusHandler</code> element.
130: *
131: * @param id
132: * the id to set
133: */
134: public void setId(String id) {
135: this.id = id;
136: }
137: }
|