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