001/**
002 *
003 * Copyright 2003-2007 Jive Software.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.jivesoftware.smackx.workgroup.packet;
019
020import java.text.SimpleDateFormat;
021import java.util.ArrayList;
022import java.util.Collections;
023import java.util.Date;
024import java.util.List;
025import java.util.TimeZone;
026
027import org.jivesoftware.smack.packet.IQ;
028import org.jxmpp.jid.Jid;
029
030/**
031 * Represents a list of conversation transcripts that a user had in all his history. Each
032 * transcript summary includes the sessionID which may be used for getting more detailed
033 * information about the conversation. {@link org.jivesoftware.smackx.workgroup.packet.Transcript}
034 *
035 * @author Gaston Dombiak
036 */
037public class Transcripts extends IQ {
038
039    private static final SimpleDateFormat UTC_FORMAT = new SimpleDateFormat("yyyyMMdd'T'HH:mm:ss");
040    static {
041        UTC_FORMAT.setTimeZone(TimeZone.getTimeZone("GMT+0"));
042    }
043
044    private Jid userID;
045    private List<Transcripts.TranscriptSummary> summaries;
046
047
048    /**
049     * Creates a transcripts request for the given userID.
050     *
051     * @param userID the id of the user to get his conversations transcripts.
052     */
053    public Transcripts(Jid userID) {
054        this(userID, new ArrayList<Transcripts.TranscriptSummary>());
055    }
056
057    /**
058     * Creates a Transcripts which will contain the transcript summaries of the given user.
059     *
060     * @param userID the id of the user. Could be a real JID or a unique String that identifies
061     *        anonymous users.
062     * @param summaries the list of TranscriptSummaries.
063     */
064    public Transcripts(Jid userID, List<Transcripts.TranscriptSummary> summaries) {
065        super("transcripts", "http://jabber.org/protocol/workgroup");
066        this.userID = userID;
067        this.summaries = summaries;
068    }
069
070    /**
071     * Returns the id of the user that was involved in the conversations. The userID could be a
072     * real JID if the connected user was not anonymous. Otherwise, the userID will be a String
073     * that was provided by the anonymous user as a way to idenitify the user across many user
074     * sessions.
075     *
076     * @return the id of the user that was involved in the conversations.
077     */
078    public Jid getUserID() {
079        return userID;
080    }
081
082    /**
083     * Returns a list of TranscriptSummary. A TranscriptSummary does not contain the conversation
084     * transcript but some summary information like the sessionID and the time when the
085     * conversation started and finished. Once you have the sessionID it is possible to get the
086     * full conversation transcript.
087     *
088     * @return a list of TranscriptSummary.
089     */
090    public List<Transcripts.TranscriptSummary> getSummaries() {
091        return Collections.unmodifiableList(summaries);
092    }
093
094    @Override
095    protected IQChildElementXmlStringBuilder getIQChildElementBuilder(IQChildElementXmlStringBuilder buf) {
096        buf.append(" userID=\"")
097                .append(userID)
098                .append("\">");
099
100        for (TranscriptSummary transcriptSummary : summaries) {
101            buf.append(transcriptSummary.toXML());
102        }
103
104        return buf;
105    }
106
107    /**
108     * A TranscriptSummary contains some information about a conversation such as the ID of the
109     * session or the date when the conversation started and finished. You will need to use the
110     * sessionID to get the full conversation transcript.
111     */
112    public static class TranscriptSummary {
113        private String sessionID;
114        private Date joinTime;
115        private Date leftTime;
116        private List<AgentDetail> agentDetails;
117
118        public TranscriptSummary(String sessionID, Date joinTime, Date leftTime, List<AgentDetail> agentDetails) {
119            this.sessionID = sessionID;
120            this.joinTime = joinTime;
121            this.leftTime = leftTime;
122            this.agentDetails = agentDetails;
123        }
124
125        /**
126         * Returns the ID of the session that is related to this conversation transcript. The
127         * sessionID could be used for getting the full conversation transcript.
128         *
129         * @return the ID of the session that is related to this conversation transcript.
130         */
131        public String getSessionID() {
132            return sessionID;
133        }
134
135        /**
136         * Returns the Date when the conversation started.
137         *
138         * @return the Date when the conversation started.
139         */
140        public Date getJoinTime() {
141            return joinTime;
142        }
143
144        /**
145         * Returns the Date when the conversation finished.
146         *
147         * @return the Date when the conversation finished.
148         */
149        public Date getLeftTime() {
150            return leftTime;
151        }
152
153        /**
154         * Returns a list of AgentDetails. For each Agent that was involved in the conversation
155         * the list will include an AgentDetail. An AgentDetail contains the JID of the agent
156         * as well as the time when the Agent joined and left the conversation.
157         *
158         * @return a list of AgentDetails.
159         */
160        public List<AgentDetail> getAgentDetails() {
161            return agentDetails;
162        }
163
164        public String toXML() {
165            StringBuilder buf = new StringBuilder();
166
167            buf.append("<transcript sessionID=\"")
168                    .append(sessionID)
169                    .append("\">");
170
171            if (joinTime != null) {
172                buf.append("<joinTime>").append(UTC_FORMAT.format(joinTime)).append("</joinTime>");
173            }
174            if (leftTime != null) {
175                buf.append("<leftTime>").append(UTC_FORMAT.format(leftTime)).append("</leftTime>");
176            }
177            buf.append("<agents>");
178            for (AgentDetail agentDetail : agentDetails) {
179                buf.append(agentDetail.toXML());
180            }
181            buf.append("</agents></transcript>");
182
183            return buf.toString();
184        }
185    }
186
187    /**
188     * An AgentDetail contains information of an Agent that was involved in a conversation. 
189     */
190    public static class AgentDetail {
191        private String agentJID;
192        private Date joinTime;
193        private Date leftTime;
194
195        public AgentDetail(String agentJID, Date joinTime, Date leftTime) {
196            this.agentJID = agentJID;
197            this.joinTime = joinTime;
198            this.leftTime = leftTime;
199        }
200
201        /**
202         * Returns the bare JID of the Agent that was involved in the conversation.
203         *
204         * @return the bared JID of the Agent that was involved in the conversation.
205         */
206        public String getAgentJID() {
207            return agentJID;
208        }
209
210        /**
211         * Returns the Date when the Agent joined the conversation.
212         *
213         * @return the Date when the Agent joined the conversation.
214         */
215        public Date getJoinTime() {
216            return joinTime;
217        }
218
219        /**
220         * Returns the Date when the Agent left the conversation.
221         *
222         * @return the Date when the Agent left the conversation.
223         */
224        public Date getLeftTime() {
225            return leftTime;
226        }
227
228        public String toXML() {
229            StringBuilder buf = new StringBuilder();
230
231            buf.append("<agent>");
232
233            if (agentJID != null) {
234                buf.append("<agentJID>").append(agentJID).append("</agentJID>");
235            }
236            if (joinTime != null) {
237                buf.append("<joinTime>").append(UTC_FORMAT.format(joinTime)).append("</joinTime>");
238            }
239            if (leftTime != null) {
240                buf.append("<leftTime>").append(UTC_FORMAT.format(leftTime)).append("</leftTime>");
241            }
242            buf.append("</agent>");
243
244            return buf.toString();
245        }
246    }
247}