/protocols/smpp/src/main/java/org/mobicents/protocols/smpp/util/APIConfig.java

  1/*
  2 * JBoss, Home of Professional Open Source
  3 * Copyright 2011, Red Hat, Inc. and individual contributors
  4 * by the @authors tag. See the copyright.txt in the distribution for a
  5 * full listing of individual contributors.
  6 *
  7 * This is free software; you can redistribute it and/or modify it
  8 * under the terms of the GNU Lesser General Public License as
  9 * published by the Free Software Foundation; either version 2.1 of
 10 * the License, or (at your option) any later version.
 11 *
 12 * This software is distributed in the hope that it will be useful,
 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 15 * Lesser General Public License for more details.
 16 *
 17 * You should have received a copy of the GNU Lesser General Public
 18 * License along with this software; if not, write to the Free
 19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 20 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 21 */
 22
 23package org.mobicents.protocols.smpp.util;
 24
 25
 26/**
 27 * Interface for internal API configuration implementations.
 28 * Implementation of this class hold the configuration for
 29 * the smppapi. The API configuration is loaded by the
 30 * {@link APIConfigFactory} class.
 31 * <p>
 32 * Implementations <strong>must</strong> supply a no-argument constructor
 33 * so that <tt>APIConfigFactory</tt> can instantiate it.
 34 * </p>
 35 * <p>
 36 * Most applications can probably accept the default settings of the API. If,
 37 * however, you're trying to eke maximum performance out of your application,
 38 * tweaking these settings may help.
 39 * </p>
 40 * <p>
 41 * Supported API properties are:
 42 * </p>
 43 * <table cols="3" border="1" width="100%">
 44 * <tr>
 45 * <th width="25%">Property name</th>
 46 * <th width="25%">Type</th>
 47 * <th width="50%">Description</th>
 48 * </tr>
 49 * 
 50 * <tr>
 51 * <td><code>smppapi.default_version</code></td>
 52 * <td>String</td>
 53 * <td>Set the default version that will be used for new Connections</td>
 54 * </tr>
 55 * 
 56 * <tr>
 57 * <td><code>smppapi.default_alphabet</code></td>
 58 * <td>String</td>
 59 * <td>The class name of the default alphabet encoding to use. Must be
 60 * an implementation of <tt>org.mobicents.smpp.util.AlphabetEncoding</tt></td>
 61 * </tr>
 62 * 
 63 * <tr>
 64 * <td><code>smppapi.lax_versions</code></td>
 65 * <td>Boolean</td>
 66 * <td>
 67 * Enable or disable interpreting interface_version values of
 68 * 0x00 thru 0x32 (inclusive) as SMPP version 3.3. The specification
 69 * is not entirely clear in its statement on whether this is allowed
 70 * or not.
 71 * </td>
 72 * </tr>
 73 * 
 74 * <tr>
 75 * <td><code>smppapi.net.buffersize_in</code></td>
 76 * <td>Integer</td>
 77 * <td>Sets the size of the buffer, in bytes, used on the incoming
 78 * stream connection from the SMSC.</td>
 79 * </tr>
 80 * 
 81 * <tr>
 82 * <td><code>smppapi.net.buffersize_out</code></td>
 83 * <td>Integer</td>
 84 * <td>Sets the size of the buffer, in bytes, used on the outgoing stream
 85 * connection to the SMSC.</td>
 86 * </tr>
 87 * 
 88 * <tr>
 89 * <td><code>smppapi.net.autoflush</code></td>
 90 * <td>Boolean</td>
 91 * <td>By default, the {@link org.mobicents.protocols.smpp.net.SmscLink} class automatically
 92 * flushes the output stream after every packet written to the output stream. In
 93 * high-load environments, it may be better to turn this off and manually flush
 94 * the output stream only when required (after a short period of inactivity, for
 95 * example).</td>
 96 * </tr>
 97 * 
 98 * <tr>
 99 * <td><code>smppapi.net.autoclose_snoop</code></td>
100 * <td>Boolean</td>
101 * <td>If snoop streams are set on the SMSC link object and this value is true
102 * (the default), the snoop streams will be closed when the link is closed. If
103 * false, the snoop streams will be flushed and left open when the link is
104 * closed.</td>
105 * </tr>
106 * 
107 * <tr>
108 * <td><code>smppapi.net.link_timeout</code></td>
109 * <td>Long</td>
110 * <td>Sets the timeout in milliseconds for network links. This value affects
111 * how long network reads should block for but its exact interpretation is
112 * link-implementation specific. For <code>TcpLink</code>, this value represents
113 * the <code>SO_TIMEOUT</code> setting on the TCP/IP socket.</td>
114 * </tr>
115 * 
116 * <tr>
117 * <td><code>smppapi.connection.bind_timeout</code></td>
118 * <td>Long</td>
119 * <td>The length of time, in milliseconds, to wait for a bind response packet
120 * after sending a bind request. If a packet is not received within this time
121 * period, the network connection is closed. A negative value or zero means wait
122 * indefinitely.</td>
123 * </tr>
124 * 
125 * <tr>
126 * <td><code>smppapi.connection.rcv_daemon.ioex_count</code></td>
127 * <td>Integer</td>
128 * <td>The number of I/O exceptions the receiver daemon will accept occurring
129 * before exiting.</td>
130 * </tr>
131 * 
132 * <tr>
133 * <td><code>smppapi.event.dispatcher</code></td>
134 * <td>String</td>
135 * <td>The name of a class, which implements
136 * {@link org.mobicents.protocols.smpp.event.EventDispatcher}, which will be used as the default
137 * event dispatcher for <code>Connection</code> objects.</td>
138 * </tr>
139 * 
140 * <tr>
141 * <td><code>smppapi.event.threaded_dispatcher.pool_size</code></td>
142 * <td>Integer</td>
143 * <td>The size of the thread pool used by the
144 * {@link org.mobicents.protocols.smpp.event.TaskExecutorEventDispatcher} class.</td>
145 * </tr>
146 * 
147 * <tr>
148 * <td><code>smppapi.message.segment_size</code></td>
149 * <td>Integer</td>
150 * <td>The default segment size to use for concatenated short messages
151 * using optional parameters.</td>
152 * </tr>
153 * </table>
154 * @version $Id: APIConfig.java 477 2009-07-12 18:00:20Z orank $
155 * @see APIConfigFactory
156 * @see PropertiesAPIConfig
157 */
158public interface APIConfig {
159    /**
160     * @see APIConfig
161     */
162    String DEFAULT_VERSION = "smppapi.default_version";
163    
164    /**
165     * @see APIConfig
166     */
167    String DEFAULT_ALPHABET = "smppapi.default_alphabet";
168    
169    /**
170     * @see APIConfig
171     */
172    String LAX_VERSIONS = "smppapi.lax_versions";
173
174    /**
175     * @see APIConfig
176     */
177    String LINK_BUFFERSIZE_IN = "smppapi.net.buffersize_in";
178
179    /**
180     * @see APIConfig
181     */
182    String LINK_BUFFERSIZE_OUT = "smppapi.net.buffersize_out";
183
184    /**
185     * @see APIConfig
186     */
187    String LINK_AUTO_FLUSH = "smppapi.net.autoflush";
188
189    /**
190     * @see APIConfig
191     */
192    String LINK_AUTOCLOSE_SNOOP = "smppapi.net.autoclose_snoop";
193
194    /**
195     * @see APIConfig
196     */
197    String LINK_TIMEOUT = "smppapi.net.link_timeout";
198
199    /**
200     * @see APIConfig
201     */
202    String TOO_MANY_IO_EXCEPTIONS = "smppapi.connection.rcv_daemon.ioex_count";
203
204    /**
205     * @see APIConfig
206     */
207    String EVENT_DISPATCHER_CLASS = "smppapi.event.dispatcher";
208
209    /**
210     * @see APIConfig
211     */
212    String EVENT_THREAD_POOL_SIZE =
213        "smppapi.event.threaded_dispatcher.pool_size";
214
215    /**
216     * @see APIConfig
217     */
218    String BIND_TIMEOUT ="smppapi.connection.bind_timeout";
219
220    /**
221     * @see APIConfig
222     */
223    String SEGMENT_SIZE = "smppapi.message.segment_size";
224    
225    /**
226     * Initialise this properties instance. The {@link APIConfigFactory}
227     * will call this method once after it has instantiated the
228     * configuration implementation so that any implementation-specific
229     * actions can be carried out.
230     */
231    void initialise();
232    
233    /**
234     * Cause the API properties to be reloaded. The properties will be re-read
235     * from the same location as they were initially loaded from. If the
236     * resource has disappeared or is no longer accessible, the properties will
237     * not be loaded and <code>false</code> will be returned to the caller.
238     * @return <tt>true</tt> if the properties were successfully reloaded,
239     * <tt>false</tt> otherwise.
240     */
241    boolean reloadAPIConfig();
242
243    /**
244     * Get the value for a property.
245     * @param property The name of the property to retrieve.
246     * @return The value for <code>property</code>.
247     * @throws PropertyNotFoundException if <code>property</code> is
248     * not found in the configuration.
249     */
250    String getProperty(String property) throws PropertyNotFoundException;
251
252    /**
253     * Get the value for a property or return a default value if it is not set.
254     * @param property The name of the property to retrieve.
255     * @param defaultValue The value to return if <code>property</code> is not
256     * set.
257     * @return The value for <code>property</code>.
258     */
259    String getProperty(String property, String defaultValue);
260
261    /**
262     * Get the value of a property, parsed as a <code>short</code>. If the
263     * property is not set, the default value is returned.
264     * @param property The name of the property to retrieve the value for.
265     * @param defaultValue The default value to return if the property is
266     * not set.
267     * @return The value for <code>property</code>.
268     * @throws InvalidConfigurationException If the value cannot be parsed as
269     * a <code>short</code>.
270     */
271    short getShort(String property, short defaultValue) throws InvalidConfigurationException;
272    
273    /**
274     * Get the value for a property, parsed as a Java <code>short</code>.
275     * @param property the name of the property to retrive.
276     * @return The value of <tt>property</tt>.
277     * @throws PropertyNotFoundException if <code>property</code> is not
278     * found in the configuration.
279     * @throws InvalidConfigurationException if the value is not a valid short.
280     */
281    short getShort(String property) throws InvalidConfigurationException, PropertyNotFoundException;
282    
283    /**
284     * Get the value for a property, parsed as a Java <code>int</code>. If
285     * the property is not found, the default value is returned.
286     * @param property the name of the property to retrive.
287     * @param defaultValue the value to return if the property does not exist.
288     * @return The value of <tt>property</tt>.
289     * @throws InvalidConfigurationException if the value is not a valid
290     * integer.
291     */
292    int getInt(String property, int defaultValue) throws InvalidConfigurationException;
293
294    /**
295     * Get the value for a property, parsed as a Java <code>int</code>.
296     * @param property the name of the property to retrive.
297     * @return The value of <tt>property</tt>.
298     * @throws PropertyNotFoundException if
299     * <code>property</code> is not found in the configuration.
300     * @throws InvalidConfigurationException if the value is not a valid
301     * integer.
302     */
303    int getInt(String property) throws InvalidConfigurationException, PropertyNotFoundException;
304
305    /**
306     * Get the value for a property, parsed as a Java <code>long</code>. If
307     * the property is not found, the default value is returned.
308     * @param property the name of the property to retrieve.
309     * @param defaultValue the value to return if the property does not exist.
310     * @return The value of <tt>property</tt>.
311     * @throws InvalidConfigurationException if the value is not a valid long.
312     */
313    long getLong(String property, long defaultValue) throws InvalidConfigurationException;
314
315    /**
316     * Get the value for a property, parsed as a Java <code>long</code>.
317     * @param property the name of the property to retrive.
318     * @return The value of <tt>property</tt>.
319     * @throws PropertyNotFoundException if <code>property</code> is not
320     * found in the configuration.
321     * @throws InvalidConfigurationException if the value is not a valid long.
322     */
323    long getLong(String property) throws InvalidConfigurationException, PropertyNotFoundException;
324
325    /**
326     * Get a property as a boolean value. Any of 'on', 'yes' or 'true'
327     * (irrelevant of case) will evaluate to <code>true</code>. Any of 'off',
328     * 'no' or 'false' will evaluate to <code>false</code>. Boolean
329     * parameters may also be specified as a number, where zero will equate to
330     * <code>false</code> while non-zero will equate to <code>true</code>.
331     * All other words will result in an InvalidConfigurationException being
332     * thrown.
333     * @param property the name of the property to look up.
334     * @param defaultValue the value to return if the property does not exist.
335     * @return The value of <tt>property</tt>.
336     * @throws InvalidConfigurationException if the property has a
337     * value that cannot be parsed or interpreted as boolean.
338     */
339    boolean getBoolean(String property, boolean defaultValue) throws InvalidConfigurationException;
340
341    /**
342     * Get a property as a boolean value. See the description of
343     * {@link #getBoolean(String, boolean)} for details of how a boolean
344     * value can be specified.
345     * @param property The name of the property to retrieve.
346     * @return The value of <tt>property</tt>.
347     * @throws PropertyNotFoundException if <code>property</code> is not
348     * found in the configuration.
349     * @throws InvalidConfigurationException if the property has a value
350     * that cannot be parsed or interpreted as boolean.
351     */
352    boolean getBoolean(String property) throws InvalidConfigurationException, PropertyNotFoundException;
353
354    /**
355     * Instantiate a new instance of a class whose class name is specified
356     * in <tt>property</tt>.
357     * @param <T> The expected type of the instantiated class.
358     * @param property The name of a property whose value is the fully
359     * qualified name of a class to instantiate.
360     * @param type The expected type of the instantiated class. This may
361     * specify a super-class or interface of the actually instantiated
362     * class.
363     * @return The new object instance.
364     * @throws PropertyNotFoundException If <tt>property</tt> is not
365     * found in the configuration.
366     */
367    <T> T getClassInstance(String property, Class<T> type);
368    
369    /**
370     * Instantiate a new instance of a class whose class name is specified
371     * in <tt>property</tt>, returning a default value if the property
372     * is not set.
373     * @param <T> The expected type of the instantiated class.
374     * @param property The name of a property whose value is the fully
375     * qualified name of a class to instantiate.
376     * @param type The expected type of the instantiated class. This may
377     * specify a super-class or interface of the actually instantiated
378     * class.
379     * @return The new object instance, or <tt>defaultValue</tt> if
380     * <tt>property</tt> is not set.
381     */
382    <T> T getClassInstance(String property, Class<T> type, T defaultValue);
383    
384    /**
385     * Determine if a property is set in the configuration.
386     * @param property The name of the property to test.
387     * @return <tt>true</tt> if the property is set, <tt>false</tt> if not.
388     */
389    boolean isSet(String property);
390}