/protocols/ss7/map/map-api/src/main/java/org/mobicents/protocols/ss7/map/api/MAPDialog.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.ss7.map.api;
 24
 25import org.mobicents.protocols.ss7.map.api.dialog.MAPDialogState;
 26import org.mobicents.protocols.ss7.map.api.dialog.MAPUserAbortChoice;
 27import org.mobicents.protocols.ss7.map.api.dialog.Reason;
 28import org.mobicents.protocols.ss7.map.api.errors.MAPErrorMessage;
 29import org.mobicents.protocols.ss7.map.api.primitives.AddressString;
 30import org.mobicents.protocols.ss7.map.api.primitives.IMSI;
 31import org.mobicents.protocols.ss7.map.api.primitives.MAPExtensionContainer;
 32import org.mobicents.protocols.ss7.tcap.api.tc.dialog.Dialog;
 33import org.mobicents.protocols.ss7.tcap.asn.comp.Invoke;
 34import org.mobicents.protocols.ss7.tcap.asn.comp.Problem;
 35import org.mobicents.protocols.ss7.tcap.asn.comp.ReturnResult;
 36import org.mobicents.protocols.ss7.tcap.asn.comp.ReturnResultLast;
 37
 38/**
 39 * 
 40 * @author amit bhayani
 41 * 
 42 */
 43public interface MAPDialog {
 44
 45	public static int _Timer_s = 10000;
 46	public static int _Timer_m = 30000;
 47	public static int _Timer_ml = 600000;
 48	public static int _Timer_l = 136800000;
 49
 50	public static int _Timer_Default = -1;
 51
 52	/**
 53	 * Returns the current {@link MAPDialogState} of this Dialog
 54	 * 
 55	 * @return
 56	 */
 57	public MAPDialogState getState();
 58
 59	/**
 60	 * Remove MAPDialog without sending any messages and invoking events
 61	 */
 62	public void release();
 63
 64	/**
 65	 * This method can be called on timeout of dialog, inside
 66	 * {@link MAPDialogListener#onDialogTimeout(Dialog)} callback. If its
 67	 * called, dialog wont be removed in case application does not perform
 68	 * 'send'.
 69	 */
 70	public void keepAlive();
 71
 72	/**
 73	 * Returns this Dialog's ID. This ID is actually TCAP's Dialog ID.
 74	 * {@link org.mobicents.protocols.ss7.tcap.api.tc.dialog.Dialog}
 75	 * 
 76	 * @return
 77	 */
 78	public Long getDialogId();
 79
 80	/**
 81	 * Returns the MAP service that serve this dialog
 82	 * 
 83	 * @return
 84	 */
 85	public MAPServiceBase getService();
 86
 87	/**
 88	 * Set ExtentionContainer that will be send in 1) T-BEGIN 2) T-CONTINUE or
 89	 * T-END if it is response to the T-BEGIN 3) T-ABORT If no Dialogue control
 90	 * APDU is sending - ExtentionContainer will also not be sent
 91	 */
 92	public void setExtentionContainer(MAPExtensionContainer extContainer);
 93
 94	/**
 95	 * This is equivalent of MAP User issuing the MAP_DELIMITER Service Request.
 96	 * send() is called to explicitly request the transfer of the MAP protocol
 97	 * data units to the peer entities.
 98	 */
 99	public void send() throws MAPException;
100
101	/**
102	 * This is equivalent of MAP User issuing the MAP_CLOSE Service Request.
103	 * This service is used for releasing a previously established MAP dialogue.
104	 * The service may be invoked by either MAP service-user depending on rules
105	 * defined within the service-user.
106	 * 
107	 * <br/>
108	 * 
109	 * If prearrangedEnd is false, all the Service Primitive added to MAPDialog
110	 * and not sent yet, will be sent to peer.
111	 * 
112	 * <br/>
113	 * 
114	 * If prearrangedEnd is true, all the Service Primitive added to MAPDialog
115	 * and not sent yet, will not be sent to peer.
116	 * 
117	 * @param prearrangedEnd
118	 */
119	public void close(boolean prearrangedEnd) throws MAPException;
120
121	/**
122	 * This is equivalent to MAP User issuing the MAP_U_ABORT Service Request.
123	 * 
124	 * @param userReason
125	 */
126	public void abort(MAPUserAbortChoice mapUserAbortChoice) throws MAPException;
127
128	/**
129	 * Send T_U_ABORT with MAP-RefuseInfo
130	 */
131	public void refuse(Reason reason) throws MAPException;
132
133	/**
134	 * Sends the TC-INVOKE component
135	 * 
136	 * @param invoke
137	 * @throws MAPException
138	 */
139	public void sendInvokeComponent(Invoke invoke) throws MAPException;
140
141	/**
142	 * Sends the TC-RESULT-NL component
143	 * 
144	 * @param returnResult
145	 * @throws MAPException
146	 */
147	public void sendReturnResultComponent(ReturnResult returnResult) throws MAPException;
148
149	/**
150	 * Sends the TC-RESULT-L component
151	 * 
152	 * @param returnResultLast
153	 * @throws MAPException
154	 */
155	public void sendReturnResultLastComponent(ReturnResultLast returnResultLast) throws MAPException;
156
157	/**
158	 * Sends the TC-U-ERROR component
159	 * 
160	 * @param invokeId
161	 * @param mapErrorMessage
162	 * @throws MAPException
163	 */
164	public void sendErrorComponent(Long invokeId, MAPErrorMessage mapErrorMessage) throws MAPException;
165
166	/**
167	 * Sends the TC-U-REJECT component
168	 * 
169	 * @param invokeId
170	 *            This parameter is optional and may be the null
171	 * @param problem
172	 * @throws MAPException
173	 */
174	public void sendRejectComponent(Long invokeId, Problem problem) throws MAPException;
175
176	/**
177	 * Reset the Invoke Timeout timer for the Invoke. (TC-TIMER-RESET)
178	 * 
179	 * @param invokeId
180	 * @throws MAPException
181	 */
182	public void resetInvokeTimer(Long invokeId) throws MAPException;
183
184	/**
185	 * Causes local termination of an operation invocation (TC-U-CANCEL)
186	 * 
187	 * @param invokeId
188	 * @return true:OK, false: Invoke not found
189	 * @throws MAPException
190	 */
191	public boolean cancelInvocation(Long invokeId) throws MAPException;
192
193	/**
194	 * Getting from the MAPDialog a user-defined object to save relating to the
195	 * Dialog information
196	 * 
197	 * @return
198	 */
199	public Object getUserObject();
200
201	/**
202	 * Store in the MAPDialog a user-defined object to save relating to the
203	 * Dialog information
204	 * 
205	 * @param userObject
206	 */
207	public void setUserObject(Object userObject);
208
209	public MAPApplicationContext getApplicationContext();
210
211	/**
212	 * Return the maximum MAP message length (in bytes) that are allowed for
213	 * this dialog
214	 * 
215	 * @return
216	 */
217	public int getMaxUserDataLength();
218
219	/**
220	 * Return the MAP message length (in bytes) that will be after encoding if
221	 * TC-BEGIN or TC-CONTINUE cases This value must not exceed
222	 * getMaxUserDataLength() value
223	 * 
224	 * @return
225	 */
226	public int getMessageUserDataLengthOnSend() throws MAPException;
227	
228	/**
229	 * Return the MAP message length (in bytes) that will be after encoding
230	 * if TC-END case
231	 * This value must not exceed getMaxUserDataLength() value
232	 * @param prearrangedEnd
233	 * @return
234	 */
235	public int getMessageUserDataLengthOnClose(boolean prearrangedEnd) throws MAPException;
236	
237	/**
238	 * This method should be invoked after MAPDialog creation
239	 * if Ericsson-style ASN.1 syntax is used
240	 * 
241	 * @param imsi
242	 * @param vlrNo
243	 */
244	public void addEricssonData(IMSI imsi, AddressString vlrNo);
245}
246