001/**
002 *
003 * Copyright © 2014-2018 Florian Schmaus
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 */
017package org.jxmpp.jid.parts;
018
019import org.jxmpp.stringprep.XmppStringPrepUtil;
020import org.jxmpp.stringprep.XmppStringprepException;
021
022/**
023 * A <i>resourcepart</i> of an XMPP address (JID).
024 * <p>
025 * You can create instances of this class from Strings using {@link #from(String)}.
026 * </p>
027 *
028 * @see <a href="http://xmpp.org/rfcs/rfc6122.html#addressing-resource">RFC 6122 § 2.4. Resourcepart</a>
029 */
030public class Resourcepart extends Part {
031
032        /**
033         *
034         */
035        private static final long serialVersionUID = 1L;
036
037        /**
038         * The empty resource part.
039         * <p>
040         * This empty resource part is the part that is represented by the empty String. This is useful in cases where you
041         * have a collection of Resourceparts that does not allow <code>null</code> values, but you want to deal with the
042         * "no resource" case.
043         * </p>
044         */
045        public static final Resourcepart EMPTY = new Resourcepart("");
046
047        private Resourcepart(String resource) {
048                super(resource);
049        }
050
051        /**
052         * Get a {@link Resourcepart} from a given {@link CharSequence} or {@code null} if the input is not a valid resourcepart.
053         *
054         * @param cs the input CharSequence
055         * @return a Resourcepart or {@code null}
056         */
057        public static Resourcepart fromOrNull(CharSequence cs) {
058                try {
059                        return from(cs.toString());
060                } catch (XmppStringprepException e) {
061                        return null;
062                }
063        }
064
065        /**
066         * Like {@link #from(String)} but does throw an unchecked {@link IllegalArgumentException} instead of a
067         * {@link XmppStringprepException}.
068         *
069         * @param cs the character sequence which should be transformed to a {@link Resourcepart}
070         * @return the {@link Resourcepart} if no exception occurs
071         * @throws IllegalArgumentException if the given input is not a valid {@link Resourcepart}
072         * @see #from(String)
073         * @since 0.6.2
074         */
075        public static Resourcepart fromOrThrowUnchecked(CharSequence cs) {
076                try {
077                        return from(cs.toString());
078                } catch (XmppStringprepException e) {
079                        throw new IllegalArgumentException(e);
080                }
081        }
082
083        /**
084         * Get the {@link Resourcepart} representing the input String.
085         *
086         * @param resource the input String.
087         * @return the resource part.
088         * @throws XmppStringprepException if an error occurs.
089         */
090        public static Resourcepart from(String resource) throws XmppStringprepException {
091                resource = XmppStringPrepUtil.resourceprep(resource);
092                // First prep the String, then assure the limits of the *result*
093                assertNotLongerThan1023BytesOrEmpty(resource);
094                return new Resourcepart(resource);
095        }
096}