org.jivesoftware.smackx.privacy.package-info Maven / Gradle / Ivy
/**
*
* Copyright 2015 Florian Schmaus
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Smacks implementation of XEP-0016: Privacy Lists.
* What is it?
*
* Privacy is a method for users to block communications from particular other users. In XMPP this is done
* by managing one’s privacy lists.
*
*
* Server-side privacy lists enable successful completion of the following use cases:
*
*
* - Retrieving one’s privacy lists.
* - Adding, removing, and editing one’s privacy lists.
* - Setting, changing, or declining active lists.
* - Setting, changing, or declining the default list (i.e., the list that is active by default).
* - Allowing or blocking messages based on JID, group, or subscription type (or globally).
* - Allowing or blocking inbound presence notifications based on JID, group, or subscription type (or globally).
* - Allowing or blocking outbound presence notifications based on JID, group, or subscription type (or
* globally).
* - Allowing or blocking IQ stanzas based on JID, group, or subscription type (or globally).
* - Allowing or blocking all communications based on JID, group, or subscription type (or globally).
*
* How can I use it?
*
* The API implementation releases three main public classes:
*
*
* PrivacyListManager: this is the main API class to retrieve and handle server privacy lists.PrivacyList: witch represents one privacy list, with a name, a set of privacy items. For example,
* the list with visible or invisible.PrivacyItem: block or allow one aspect of privacy. For example, to allow my friend to see my
* presence.
*
* - Right from the start, a client MAY get his/her privacy list that is stored in the server:
*
*
*
*
* // Create a privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Retrieve server privacy lists_
* PrivacyList[] lists = privacyManager.getPrivacyLists();
*
*
*
* Now the client is able to show every PrivacyItem of the server and also for every list if it is active,
* default or none of them. The client is a listener of privacy changes.
*
*
* - In order to add a new list in the server, the client MAY implement something like:
*
*
*
*
* // Set the name of the list_
* String listName = "newList";
*
* // Create the list of PrivacyItem that will allow or deny some privacy aspect_
* String user = "[email protected]";
* String groupName = "enemies";
* ArrayList privacyItems = new ArrayList();
*
* PrivacyItem item = new PrivacyItem(PrivacyItem.Type.jid, user, true, 1);
* privacyItems.add(item);
*
* item = new PrivacyItem(PrivacyItem.Type.subscription, PrivacyItem.SUBSCRIPTION_BOTH, true, 2);
* privacyItems.add(item);
*
* item = new PrivacyItem(PrivacyItem.Type.group, groupName, false, 3);
* item.setFilterMessage(true);
* privacyItems.add(item);
*
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Create the new list._
* privacyManager.createPrivacyList(listName, privacyItems);
*
*
*
* - To modify an existent list, the client code MAY be like:
*
*
*
*
* // Set the name of the list_
* String listName = "existingList";
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Sent the new list to the server._
* privacyManager.updatePrivacyList(listName, items);
*
*
*
* Notice items was defined at the example 2 and MUST contain all the elements in the list (not the
* “delta”).
*
*
* - In order to delete an existing list, the client MAY perform something like:
*
*
*
*
* // Set the name of the list_
* String listName = "existingList";
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Remove the list._
* privacyManager.deletePrivacyList(listName);
*
*
*
* - In order to decline the use of an active list, the client MAY perform something like:
*
*
*
*
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Decline the use of the active list._
* privacyManager.declineActiveList();
*
*
*
* - In order to decline the use of a default list, the client MAY perform something like:
*
*
*
*
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Decline the use of the default list._
* privacyManager.declineDefaultList();
*
*
*
* Listening for Privacy Changes
*
*
* In order to handle privacy changes, clients SHOULD listen manager’s updates. When a list is changed the manager
* notifies every added listener. Listeners MUST implement the PrivacyListListener interface. Clients may
* need to react when a privacy list is modified. The PrivacyListManager lets you add listeners that will
* be notified when a list has been changed. Listeners should implement the PrivacyListListener interface.
*
*
* The most important notification is updatedPrivacyList that is performed when a privacy list changes its
* privacy items.
*
*
* The listener becomes notified after performing:
*
*
*
*
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Add the listener (this) to get notified_
* privacyManager.addListener(this);
*
*
*/
package org.jivesoftware.smackx.privacy;