001/**
002 * Copyright 2011 Bill Brown
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package com.colorfulsoftware.rss;
017
018import java.io.Serializable;
019
020/**
021 * <p>
022 * The &lt;guid> element.
023 * </p>
024 * <p>
025 * From the <a href="http://cyber.law.harvard.edu/rss/rss.html">RSS 2.0
026 * specification</a>...
027 * </p>
028 * <p>
029 * A string that uniquely identifies the item. <a href=
030 * "http://cyber.law.harvard.edu/rss/rss.html#ltguidgtSubelementOfLtitemgt"
031 * >More</a>.
032 * </p>
033 * 
034 * <p>
035 * &lt;guid> is an optional sub-element of &lt;item>.
036 * </p>
037 * 
038 * <p>
039 * guid stands for globally unique identifier. It's a string that uniquely
040 * identifies the item. When present, an aggregator may choose to use this
041 * string to determine if an item is new.
042 * </p>
043 * 
044 * <p>
045 * &lt;guid>http://some.server.com/weblogItem3207&lt;/guid>
046 * </p>
047 * 
048 * <p>
049 * There are no rules for the syntax of a guid. Aggregators must view them as a
050 * string. It's up to the source of the feed to establish the uniqueness of the
051 * string.
052 * </p>
053 * 
054 * <p>
055 * If the guid element has an attribute named "isPermaLink" with a value of
056 * true, the reader may assume that it is a permalink to the item, that is, a
057 * url that can be opened in a Web browser, that points to the full item
058 * described by the &lt;item> element. An example:
059 * </p>
060 * 
061 * <p>
062 * &lt;guid
063 * isPermaLink="true">http://inessential.com/2002/09/01.php#a2&lt;/guid>
064 * </p>
065 * 
066 * <p>
067 * isPermaLink is optional, its default value is true. If its value is false,
068 * the guid may not be assumed to be a url, or a url to anything in particular.
069 * </p>
070 * 
071 * @author Bill Brown
072 * 
073 */
074public class GUID implements Serializable {
075
076        private static final long serialVersionUID = 1285259651943559185L;
077
078        private final String guid;
079        private Attribute isPermaLink;
080
081        GUID(Attribute isPermaLink, String guid) throws RSSpectException {
082                this.isPermaLink = (isPermaLink == null) ? null : new Attribute(
083                                isPermaLink);
084                if (guid == null || guid.equals("")) {
085                        throw new RSSpectException("guid SHOULD NOT be blank.");
086                }
087                this.guid = guid;
088        }
089
090        GUID(GUID guid) {
091                this.isPermaLink = guid.getIsPermaLink();
092                this.guid = guid.guid;
093        }
094
095        /**
096         * @return the guid.
097         */
098        public String getGuid() {
099                return guid;
100        }
101
102        /**
103         * @return the isPermaLink attribute.
104         */
105        public Attribute getIsPermaLink() {
106                return (isPermaLink == null) ? null : new Attribute(isPermaLink);
107        }
108
109        /**
110         * Shows the contents of the &lt;guid> element.
111         */
112        @Override
113        public String toString() {
114                StringBuilder sb = new StringBuilder("<guid");
115
116                // conditionally add the domain.
117                sb.append(((isPermaLink == null) ? ">" : isPermaLink + " >") + guid
118                                + "</guid>");
119
120                return sb.toString();
121        }
122        
123        @Override
124        public boolean equals(Object obj) {
125                if (obj == this) {
126                        return true;
127                }
128                if (!(obj instanceof GUID)) {
129                        return false;
130                }
131                return this.toString().equals(obj.toString());
132        }
133        
134        @Override public int hashCode() {
135                return toString().hashCode();
136        }
137}