001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.tools;
003
004import static org.openstreetmap.josm.tools.I18n.tr;
005import static org.openstreetmap.josm.tools.I18n.trn;
006
007import java.awt.Color;
008import java.awt.Toolkit;
009import java.awt.datatransfer.Clipboard;
010import java.awt.datatransfer.ClipboardOwner;
011import java.awt.datatransfer.DataFlavor;
012import java.awt.datatransfer.StringSelection;
013import java.awt.datatransfer.Transferable;
014import java.awt.datatransfer.UnsupportedFlavorException;
015import java.io.BufferedInputStream;
016import java.io.BufferedReader;
017import java.io.Closeable;
018import java.io.File;
019import java.io.IOException;
020import java.io.InputStream;
021import java.io.InputStreamReader;
022import java.io.OutputStream;
023import java.io.UnsupportedEncodingException;
024import java.net.HttpURLConnection;
025import java.net.MalformedURLException;
026import java.net.URL;
027import java.net.URLConnection;
028import java.net.URLEncoder;
029import java.nio.charset.StandardCharsets;
030import java.nio.file.Files;
031import java.nio.file.Path;
032import java.nio.file.StandardCopyOption;
033import java.security.MessageDigest;
034import java.security.NoSuchAlgorithmException;
035import java.text.MessageFormat;
036import java.util.AbstractCollection;
037import java.util.AbstractList;
038import java.util.ArrayList;
039import java.util.Arrays;
040import java.util.Collection;
041import java.util.Collections;
042import java.util.Iterator;
043import java.util.List;
044import java.util.concurrent.ExecutorService;
045import java.util.concurrent.Executors;
046import java.util.regex.Matcher;
047import java.util.regex.Pattern;
048import java.util.zip.GZIPInputStream;
049import java.util.zip.ZipEntry;
050import java.util.zip.ZipFile;
051import java.util.zip.ZipInputStream;
052
053import org.apache.tools.bzip2.CBZip2InputStream;
054import org.openstreetmap.josm.Main;
055import org.openstreetmap.josm.data.Version;
056
057/**
058 * Basic utils, that can be useful in different parts of the program.
059 */
060public final class Utils {
061
062    public static final Pattern WHITE_SPACES_PATTERN = Pattern.compile("\\s+");
063
064    private Utils() {
065        // Hide default constructor for utils classes
066    }
067
068    private static final int MILLIS_OF_SECOND = 1000;
069    private static final int MILLIS_OF_MINUTE = 60000;
070    private static final int MILLIS_OF_HOUR = 3600000;
071    private static final int MILLIS_OF_DAY = 86400000;
072
073    public static final String URL_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%";
074
075    /**
076     * Tests whether {@code predicate} applies to at least one elements from {@code collection}.
077     */
078    public static <T> boolean exists(Iterable<? extends T> collection, Predicate<? super T> predicate) {
079        for (T item : collection) {
080            if (predicate.evaluate(item))
081                return true;
082        }
083        return false;
084    }
085
086    /**
087     * Tests whether {@code predicate} applies to all elements from {@code collection}.
088     */
089    public static <T> boolean forAll(Iterable<? extends T> collection, Predicate<? super T> predicate) {
090        return !exists(collection, Predicates.not(predicate));
091    }
092
093    public static <T> boolean exists(Iterable<T> collection, Class<? extends T> klass) {
094        for (Object item : collection) {
095            if (klass.isInstance(item))
096                return true;
097        }
098        return false;
099    }
100
101    public static <T> T find(Iterable<? extends T> collection, Predicate<? super T> predicate) {
102        for (T item : collection) {
103            if (predicate.evaluate(item))
104                return item;
105        }
106        return null;
107    }
108
109    @SuppressWarnings("unchecked")
110    public static <T> T find(Iterable<? super T> collection, Class<? extends T> klass) {
111        for (Object item : collection) {
112            if (klass.isInstance(item))
113                return (T) item;
114        }
115        return null;
116    }
117
118    public static <T> Collection<T> filter(Collection<? extends T> collection, Predicate<? super T> predicate) {
119        return new FilteredCollection<>(collection, predicate);
120    }
121
122    /**
123     * Returns the first element from {@code items} which is non-null, or null if all elements are null.
124     * @param items the items to look for
125     * @return first non-null item if there is one
126     */
127    @SafeVarargs
128    public static <T> T firstNonNull(T... items) {
129        for (T i : items) {
130            if (i != null) {
131                return i;
132            }
133        }
134        return null;
135    }
136
137    /**
138     * Filter a collection by (sub)class.
139     * This is an efficient read-only implementation.
140     */
141    public static <S, T extends S> SubclassFilteredCollection<S, T> filteredCollection(Collection<S> collection, final Class<T> klass) {
142        return new SubclassFilteredCollection<>(collection, new Predicate<S>() {
143            @Override
144            public boolean evaluate(S o) {
145                return klass.isInstance(o);
146            }
147        });
148    }
149
150    public static <T> int indexOf(Iterable<? extends T> collection, Predicate<? super T> predicate) {
151        int i = 0;
152        for (T item : collection) {
153            if (predicate.evaluate(item))
154                return i;
155            i++;
156        }
157        return -1;
158    }
159
160    /**
161     * Get minimum of 3 values
162     */
163    public static int min(int a, int b, int c) {
164        if (b < c) {
165            if (a < b)
166                return a;
167            return b;
168        } else {
169            if (a < c)
170                return a;
171            return c;
172        }
173    }
174
175    public static int max(int a, int b, int c, int d) {
176        return Math.max(Math.max(a, b), Math.max(c, d));
177    }
178
179    public static void ensure(boolean condition, String message, Object...data) {
180        if (!condition)
181            throw new AssertionError(
182                    MessageFormat.format(message,data)
183            );
184    }
185
186    /**
187     * return the modulus in the range [0, n)
188     */
189    public static int mod(int a, int n) {
190        if (n <= 0)
191            throw new IllegalArgumentException();
192        int res = a % n;
193        if (res < 0) {
194            res += n;
195        }
196        return res;
197    }
198
199    /**
200     * Joins a list of strings (or objects that can be converted to string via
201     * Object.toString()) into a single string with fields separated by sep.
202     * @param sep the separator
203     * @param values collection of objects, null is converted to the
204     *  empty string
205     * @return null if values is null. The joined string otherwise.
206     */
207    public static String join(String sep, Collection<?> values) {
208        if (sep == null)
209            throw new IllegalArgumentException();
210        if (values == null)
211            return null;
212        if (values.isEmpty())
213            return "";
214        StringBuilder s = null;
215        for (Object a : values) {
216            if (a == null) {
217                a = "";
218            }
219            if (s != null) {
220                s.append(sep).append(a.toString());
221            } else {
222                s = new StringBuilder(a.toString());
223            }
224        }
225        return s.toString();
226    }
227
228    /**
229     * Converts the given iterable collection as an unordered HTML list.
230     * @param values The iterable collection
231     * @return An unordered HTML list
232     */
233    public static String joinAsHtmlUnorderedList(Iterable<?> values) {
234        StringBuilder sb = new StringBuilder(1024);
235        sb.append("<ul>");
236        for (Object i : values) {
237            sb.append("<li>").append(i).append("</li>");
238        }
239        sb.append("</ul>");
240        return sb.toString();
241    }
242
243    /**
244     * convert Color to String
245     * (Color.toString() omits alpha value)
246     */
247    public static String toString(Color c) {
248        if (c == null)
249            return "null";
250        if (c.getAlpha() == 255)
251            return String.format("#%06x", c.getRGB() & 0x00ffffff);
252        else
253            return String.format("#%06x(alpha=%d)", c.getRGB() & 0x00ffffff, c.getAlpha());
254    }
255
256    /**
257     * convert float range 0 &lt;= x &lt;= 1 to integer range 0..255
258     * when dealing with colors and color alpha value
259     * @return null if val is null, the corresponding int if val is in the
260     *         range 0...1. If val is outside that range, return 255
261     */
262    public static Integer color_float2int(Float val) {
263        if (val == null)
264            return null;
265        if (val < 0 || val > 1)
266            return 255;
267        return (int) (255f * val + 0.5f);
268    }
269
270    /**
271     * convert integer range 0..255 to float range 0 &lt;= x &lt;= 1
272     * when dealing with colors and color alpha value
273     */
274    public static Float color_int2float(Integer val) {
275        if (val == null)
276            return null;
277        if (val < 0 || val > 255)
278            return 1f;
279        return ((float) val) / 255f;
280    }
281
282    public static Color complement(Color clr) {
283        return new Color(255 - clr.getRed(), 255 - clr.getGreen(), 255 - clr.getBlue(), clr.getAlpha());
284    }
285
286    /**
287     * Copies the given array. Unlike {@link Arrays#copyOf}, this method is null-safe.
288     * @param array The array to copy
289     * @return A copy of the original array, or {@code null} if {@code array} is null
290     * @since 6221
291     */
292    public static <T> T[] copyArray(T[] array) {
293        if (array != null) {
294            return Arrays.copyOf(array, array.length);
295        }
296        return null;
297    }
298
299    /**
300     * Copies the given array. Unlike {@link Arrays#copyOf}, this method is null-safe.
301     * @param array The array to copy
302     * @return A copy of the original array, or {@code null} if {@code array} is null
303     * @since 6222
304     */
305    public static char[] copyArray(char[] array) {
306        if (array != null) {
307            return Arrays.copyOf(array, array.length);
308        }
309        return null;
310    }
311
312    /**
313     * Copies the given array. Unlike {@link Arrays#copyOf}, this method is null-safe.
314     * @param array The array to copy
315     * @return A copy of the original array, or {@code null} if {@code array} is null
316     * @since 7436
317     */
318    public static int[] copyArray(int[] array) {
319        if (array != null) {
320            return Arrays.copyOf(array, array.length);
321        }
322        return null;
323    }
324
325    /**
326     * Simple file copy function that will overwrite the target file.<br>
327     * @param in The source file
328     * @param out The destination file
329     * @return the path to the target file
330     * @throws java.io.IOException If any I/O error occurs
331     * @throws IllegalArgumentException If {@code in} or {@code out} is {@code null}
332     * @since 7003
333     */
334    public static Path copyFile(File in, File out) throws IOException, IllegalArgumentException  {
335        CheckParameterUtil.ensureParameterNotNull(in, "in");
336        CheckParameterUtil.ensureParameterNotNull(out, "out");
337        return Files.copy(in.toPath(), out.toPath(), StandardCopyOption.REPLACE_EXISTING);
338    }
339
340    public static int copyStream(InputStream source, OutputStream destination) throws IOException {
341        int count = 0;
342        byte[] b = new byte[512];
343        int read;
344        while ((read = source.read(b)) != -1) {
345            count += read;
346            destination.write(b, 0, read);
347        }
348        return count;
349    }
350
351    public static boolean deleteDirectory(File path) {
352        if( path.exists() ) {
353            File[] files = path.listFiles();
354            for (File file : files) {
355                if (file.isDirectory()) {
356                    deleteDirectory(file);
357                } else {
358                    file.delete();
359                }
360            }
361        }
362        return( path.delete() );
363    }
364
365    /**
366     * <p>Utility method for closing a {@link java.io.Closeable} object.</p>
367     *
368     * @param c the closeable object. May be null.
369     */
370    public static void close(Closeable c) {
371        if (c == null) return;
372        try {
373            c.close();
374        } catch (IOException e) {
375            Main.warn(e);
376        }
377    }
378
379    /**
380     * <p>Utility method for closing a {@link java.util.zip.ZipFile}.</p>
381     *
382     * @param zip the zip file. May be null.
383     */
384    public static void close(ZipFile zip) {
385        if (zip == null) return;
386        try {
387            zip.close();
388        } catch (IOException e) {
389            Main.warn(e);
390        }
391    }
392
393    /**
394     * Converts the given file to its URL.
395     * @param f The file to get URL from
396     * @return The URL of the given file, or {@code null} if not possible.
397     * @since 6615
398     */
399    public static URL fileToURL(File f) {
400        if (f != null) {
401            try {
402                return f.toURI().toURL();
403            } catch (MalformedURLException ex) {
404                Main.error("Unable to convert filename " + f.getAbsolutePath() + " to URL");
405            }
406        }
407        return null;
408    }
409
410    private static final double EPSILON = 1e-11;
411
412    /**
413     * Determines if the two given double values are equal (their delta being smaller than a fixed epsilon)
414     * @param a The first double value to compare
415     * @param b The second double value to compare
416     * @return {@code true} if {@code abs(a - b) <= 1e-11}, {@code false} otherwise
417     */
418    public static boolean equalsEpsilon(double a, double b) {
419        return Math.abs(a - b) <= EPSILON;
420    }
421
422    /**
423     * Copies the string {@code s} to system clipboard.
424     * @param s string to be copied to clipboard.
425     * @return true if succeeded, false otherwise.
426     */
427    public static boolean copyToClipboard(String s) {
428        try {
429            Toolkit.getDefaultToolkit().getSystemClipboard().setContents(new StringSelection(s), new ClipboardOwner() {
430
431                @Override
432                public void lostOwnership(Clipboard clpbrd, Transferable t) {
433                }
434            });
435            return true;
436        } catch (IllegalStateException ex) {
437            Main.error(ex);
438            return false;
439        }
440    }
441
442    /**
443     * Extracts clipboard content as string.
444     * @return string clipboard contents if available, {@code null} otherwise.
445     */
446    public static String getClipboardContent() {
447        Clipboard clipboard = Toolkit.getDefaultToolkit().getSystemClipboard();
448        Transferable t = null;
449        for (int tries = 0; t == null && tries < 10; tries++) {
450            try {
451                t = clipboard.getContents(null);
452            } catch (IllegalStateException e) {
453                // Clipboard currently unavailable. On some platforms, the system clipboard is unavailable while it is accessed by another application.
454                try {
455                    Thread.sleep(1);
456                } catch (InterruptedException ex) {
457                    Main.warn("InterruptedException in "+Utils.class.getSimpleName()+" while getting clipboard content");
458                }
459            }
460        }
461        try {
462            if (t != null && t.isDataFlavorSupported(DataFlavor.stringFlavor)) {
463                return (String) t.getTransferData(DataFlavor.stringFlavor);
464            }
465        } catch (UnsupportedFlavorException | IOException ex) {
466            Main.error(ex);
467            return null;
468        }
469        return null;
470    }
471
472    /**
473     * Calculate MD5 hash of a string and output in hexadecimal format.
474     * @param data arbitrary String
475     * @return MD5 hash of data, string of length 32 with characters in range [0-9a-f]
476     */
477    public static String md5Hex(String data) {
478        byte[] byteData = data.getBytes(StandardCharsets.UTF_8);
479        MessageDigest md = null;
480        try {
481            md = MessageDigest.getInstance("MD5");
482        } catch (NoSuchAlgorithmException e) {
483            throw new RuntimeException(e);
484        }
485        byte[] byteDigest = md.digest(byteData);
486        return toHexString(byteDigest);
487    }
488
489    private static final char[] HEX_ARRAY = {'0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f'};
490
491    /**
492     * Converts a byte array to a string of hexadecimal characters.
493     * Preserves leading zeros, so the size of the output string is always twice
494     * the number of input bytes.
495     * @param bytes the byte array
496     * @return hexadecimal representation
497     */
498    public static String toHexString(byte[] bytes) {
499
500        if (bytes == null) {
501            return "";
502        }
503
504        final int len = bytes.length;
505        if (len == 0) {
506            return "";
507        }
508
509        char[] hexChars = new char[len * 2];
510        for (int i = 0, j = 0; i < len; i++) {
511            final int v = bytes[i];
512            hexChars[j++] = HEX_ARRAY[(v & 0xf0) >> 4];
513            hexChars[j++] = HEX_ARRAY[v & 0xf];
514        }
515        return new String(hexChars);
516    }
517
518    /**
519     * Topological sort.
520     *
521     * @param dependencies contains mappings (key -&gt; value). In the final list of sorted objects, the key will come
522     * after the value. (In other words, the key depends on the value(s).)
523     * There must not be cyclic dependencies.
524     * @return the list of sorted objects
525     */
526    public static <T> List<T> topologicalSort(final MultiMap<T,T> dependencies) {
527        MultiMap<T,T> deps = new MultiMap<>();
528        for (T key : dependencies.keySet()) {
529            deps.putVoid(key);
530            for (T val : dependencies.get(key)) {
531                deps.putVoid(val);
532                deps.put(key, val);
533            }
534        }
535
536        int size = deps.size();
537        List<T> sorted = new ArrayList<>();
538        for (int i=0; i<size; ++i) {
539            T parentless = null;
540            for (T key : deps.keySet()) {
541                if (deps.get(key).isEmpty()) {
542                    parentless = key;
543                    break;
544                }
545            }
546            if (parentless == null) throw new RuntimeException();
547            sorted.add(parentless);
548            deps.remove(parentless);
549            for (T key : deps.keySet()) {
550                deps.remove(key, parentless);
551            }
552        }
553        if (sorted.size() != size) throw new RuntimeException();
554        return sorted;
555    }
556
557    /**
558     * Represents a function that can be applied to objects of {@code A} and
559     * returns objects of {@code B}.
560     * @param <A> class of input objects
561     * @param <B> class of transformed objects
562     */
563    public static interface Function<A, B> {
564
565        /**
566         * Applies the function on {@code x}.
567         * @param x an object of
568         * @return the transformed object
569         */
570        B apply(A x);
571    }
572
573    /**
574     * Transforms the collection {@code c} into an unmodifiable collection and
575     * applies the {@link org.openstreetmap.josm.tools.Utils.Function} {@code f} on each element upon access.
576     * @param <A> class of input collection
577     * @param <B> class of transformed collection
578     * @param c a collection
579     * @param f a function that transforms objects of {@code A} to objects of {@code B}
580     * @return the transformed unmodifiable collection
581     */
582    public static <A, B> Collection<B> transform(final Collection<? extends A> c, final Function<A, B> f) {
583        return new AbstractCollection<B>() {
584
585            @Override
586            public int size() {
587                return c.size();
588            }
589
590            @Override
591            public Iterator<B> iterator() {
592                return new Iterator<B>() {
593
594                    private Iterator<? extends A> it = c.iterator();
595
596                    @Override
597                    public boolean hasNext() {
598                        return it.hasNext();
599                    }
600
601                    @Override
602                    public B next() {
603                        return f.apply(it.next());
604                    }
605
606                    @Override
607                    public void remove() {
608                        throw new UnsupportedOperationException();
609                    }
610                };
611            }
612        };
613    }
614
615    /**
616     * Transforms the list {@code l} into an unmodifiable list and
617     * applies the {@link org.openstreetmap.josm.tools.Utils.Function} {@code f} on each element upon access.
618     * @param <A> class of input collection
619     * @param <B> class of transformed collection
620     * @param l a collection
621     * @param f a function that transforms objects of {@code A} to objects of {@code B}
622     * @return the transformed unmodifiable list
623     */
624    public static <A, B> List<B> transform(final List<? extends A> l, final Function<A, B> f) {
625        return new AbstractList<B>() {
626
627
628            @Override
629            public int size() {
630                return l.size();
631            }
632
633            @Override
634            public B get(int index) {
635                return f.apply(l.get(index));
636            }
637
638
639        };
640    }
641
642    private static final Pattern HTTP_PREFFIX_PATTERN = Pattern.compile("https?");
643
644    /**
645     * Opens a HTTP connection to the given URL and sets the User-Agent property to JOSM's one.
646     * @param httpURL The HTTP url to open (must use http:// or https://)
647     * @return An open HTTP connection to the given URL
648     * @throws java.io.IOException if an I/O exception occurs.
649     * @since 5587
650     */
651    public static HttpURLConnection openHttpConnection(URL httpURL) throws IOException {
652        if (httpURL == null || !HTTP_PREFFIX_PATTERN.matcher(httpURL.getProtocol()).matches()) {
653            throw new IllegalArgumentException("Invalid HTTP url");
654        }
655        if (Main.isDebugEnabled()) {
656            Main.debug("Opening HTTP connection to "+httpURL.toExternalForm());
657        }
658        HttpURLConnection connection = (HttpURLConnection) httpURL.openConnection();
659        connection.setRequestProperty("User-Agent", Version.getInstance().getFullAgentString());
660        connection.setUseCaches(false);
661        return connection;
662    }
663
664    /**
665     * Opens a connection to the given URL and sets the User-Agent property to JOSM's one.
666     * @param url The url to open
667     * @return An stream for the given URL
668     * @throws java.io.IOException if an I/O exception occurs.
669     * @since 5867
670     */
671    public static InputStream openURL(URL url) throws IOException {
672        return openURLAndDecompress(url, false);
673    }
674
675    /**
676     * Opens a connection to the given URL, sets the User-Agent property to JOSM's one, and decompresses stream if necessary.
677     * @param url The url to open
678     * @param decompress whether to wrap steam in a {@link GZIPInputStream} or {@link CBZip2InputStream}
679     *                   if the {@code Content-Type} header is set accordingly.
680     * @return An stream for the given URL
681     * @throws IOException if an I/O exception occurs.
682     * @since 6421
683     */
684    public static InputStream openURLAndDecompress(final URL url, final boolean decompress) throws IOException {
685        final URLConnection connection = setupURLConnection(url.openConnection());
686        final InputStream in = connection.getInputStream();
687        if (decompress) {
688            switch (connection.getHeaderField("Content-Type")) {
689            case "application/zip":
690                return getZipInputStream(in);
691            case "application/x-gzip":
692                return getGZipInputStream(in);
693            case "application/x-bzip2":
694                return getBZip2InputStream(in);
695            }
696        }
697        return in;
698    }
699
700    /**
701     * Returns a Bzip2 input stream wrapping given input stream.
702     * @param in The raw input stream
703     * @return a Bzip2 input stream wrapping given input stream, or {@code null} if {@code in} is {@code null}
704     * @throws IOException if the given input stream does not contain valid BZ2 header
705     * @since 7119
706     */
707    public static CBZip2InputStream getBZip2InputStream(InputStream in) throws IOException {
708        if (in == null) {
709            return null;
710        }
711        BufferedInputStream bis = new BufferedInputStream(in);
712        int b = bis.read();
713        if (b != 'B')
714            throw new IOException(tr("Invalid bz2 file."));
715        b = bis.read();
716        if (b != 'Z')
717            throw new IOException(tr("Invalid bz2 file."));
718        return new CBZip2InputStream(bis, /* see #9537 */ true);
719    }
720
721    /**
722     * Returns a Gzip input stream wrapping given input stream.
723     * @param in The raw input stream
724     * @return a Gzip input stream wrapping given input stream, or {@code null} if {@code in} is {@code null}
725     * @throws IOException if an I/O error has occurred
726     * @since 7119
727     */
728    public static GZIPInputStream getGZipInputStream(InputStream in) throws IOException {
729        if (in == null) {
730            return null;
731        }
732        return new GZIPInputStream(in);
733    }
734
735    /**
736     * Returns a Zip input stream wrapping given input stream.
737     * @param in The raw input stream
738     * @return a Zip input stream wrapping given input stream, or {@code null} if {@code in} is {@code null}
739     * @throws IOException if an I/O error has occurred
740     * @since 7119
741     */
742    public static ZipInputStream getZipInputStream(InputStream in) throws IOException {
743        if (in == null) {
744            return null;
745        }
746        ZipInputStream zis = new ZipInputStream(in, StandardCharsets.UTF_8);
747        // Positions the stream at the beginning of first entry
748        ZipEntry ze = zis.getNextEntry();
749        if (ze != null && Main.isDebugEnabled()) {
750            Main.debug("Zip entry: "+ze.getName());
751        }
752        return zis;
753    }
754
755    /***
756     * Setups the given URL connection to match JOSM needs by setting its User-Agent and timeout properties.
757     * @param connection The connection to setup
758     * @return {@code connection}, with updated properties
759     * @since 5887
760     */
761    public static URLConnection setupURLConnection(URLConnection connection) {
762        if (connection != null) {
763            connection.setRequestProperty("User-Agent", Version.getInstance().getFullAgentString());
764            connection.setConnectTimeout(Main.pref.getInteger("socket.timeout.connect",15)*1000);
765            connection.setReadTimeout(Main.pref.getInteger("socket.timeout.read",30)*1000);
766        }
767        return connection;
768    }
769
770    /**
771     * Opens a connection to the given URL and sets the User-Agent property to JOSM's one.
772     * @param url The url to open
773     * @return An buffered stream reader for the given URL (using UTF-8)
774     * @throws java.io.IOException if an I/O exception occurs.
775     * @since 5868
776     */
777    public static BufferedReader openURLReader(URL url) throws IOException {
778        return openURLReaderAndDecompress(url, false);
779    }
780
781    /**
782     * Opens a connection to the given URL and sets the User-Agent property to JOSM's one.
783     * @param url The url to open
784     * @param decompress whether to wrap steam in a {@link GZIPInputStream} or {@link CBZip2InputStream}
785     *                   if the {@code Content-Type} header is set accordingly.
786     * @return An buffered stream reader for the given URL (using UTF-8)
787     * @throws IOException if an I/O exception occurs.
788     * @since 6421
789     */
790    public static BufferedReader openURLReaderAndDecompress(final URL url, final boolean decompress) throws IOException {
791        return new BufferedReader(new InputStreamReader(openURLAndDecompress(url, decompress), StandardCharsets.UTF_8));
792    }
793
794    /**
795     * Opens a HTTP connection to the given URL, sets the User-Agent property to JOSM's one and optionnaly disables Keep-Alive.
796     * @param httpURL The HTTP url to open (must use http:// or https://)
797     * @param keepAlive whether not to set header {@code Connection=close}
798     * @return An open HTTP connection to the given URL
799     * @throws java.io.IOException if an I/O exception occurs.
800     * @since 5587
801     */
802    public static HttpURLConnection openHttpConnection(URL httpURL, boolean keepAlive) throws IOException {
803        HttpURLConnection connection = openHttpConnection(httpURL);
804        if (!keepAlive) {
805            connection.setRequestProperty("Connection", "close");
806        }
807        if (Main.isDebugEnabled()) {
808            try {
809                Main.debug("REQUEST: "+ connection.getRequestProperties());
810            } catch (IllegalStateException e) {
811                Main.warn(e);
812            }
813        }
814        return connection;
815    }
816
817    /**
818     * An alternative to {@link String#trim()} to effectively remove all leading and trailing white characters, including Unicode ones.
819     * @see <a href="http://closingbraces.net/2008/11/11/javastringtrim/">Java?s String.trim has a strange idea of whitespace</a>
820     * @see <a href="https://bugs.openjdk.java.net/browse/JDK-4080617">JDK bug 4080617</a>
821     * @param str The string to strip
822     * @return <code>str</code>, without leading and trailing characters, according to
823     *         {@link Character#isWhitespace(char)} and {@link Character#isSpaceChar(char)}.
824     * @since 5772
825     */
826    public static String strip(String str) {
827        if (str == null || str.isEmpty()) {
828            return str;
829        }
830        int start = 0, end = str.length();
831        boolean leadingWhite = true;
832        while (leadingWhite && start < end) {
833            char c = str.charAt(start);
834            // '\u200B' (ZERO WIDTH SPACE character) needs to be handled manually because of change in Unicode 6.0 (Java 7, see #8918)
835            // same for '\uFEFF' (ZERO WIDTH NO-BREAK SPACE)
836            leadingWhite = (Character.isWhitespace(c) || Character.isSpaceChar(c) || c == '\u200B' || c == '\uFEFF');
837            if (leadingWhite) {
838                start++;
839            }
840        }
841        boolean trailingWhite = true;
842        while (trailingWhite && end > start+1) {
843            char c = str.charAt(end-1);
844            trailingWhite = (Character.isWhitespace(c) || Character.isSpaceChar(c) || c == '\u200B' || c == '\uFEFF');
845            if (trailingWhite) {
846                end--;
847            }
848        }
849        return str.substring(start, end);
850    }
851
852    /**
853     * Runs an external command and returns the standard output.
854     *
855     * The program is expected to execute fast.
856     *
857     * @param command the command with arguments
858     * @return the output
859     * @throws IOException when there was an error, e.g. command does not exist
860     */
861    public static String execOutput(List<String> command) throws IOException {
862        if (Main.isDebugEnabled()) {
863            Main.debug(join(" ", command));
864        }
865        Process p = new ProcessBuilder(command).start();
866        try (BufferedReader input = new BufferedReader(new InputStreamReader(p.getInputStream(), StandardCharsets.UTF_8))) {
867            StringBuilder all = null;
868            String line;
869            while ((line = input.readLine()) != null) {
870                if (all == null) {
871                    all = new StringBuilder(line);
872                } else {
873                    all.append("\n");
874                    all.append(line);
875                }
876            }
877            return all != null ? all.toString() : null;
878        }
879    }
880
881    /**
882     * Returns the JOSM temp directory.
883     * @return The JOSM temp directory ({@code <java.io.tmpdir>/JOSM}), or {@code null} if {@code java.io.tmpdir} is not defined
884     * @since 6245
885     */
886    public static File getJosmTempDir() {
887        String tmpDir = System.getProperty("java.io.tmpdir");
888        if (tmpDir == null) {
889            return null;
890        }
891        File josmTmpDir = new File(tmpDir, "JOSM");
892        if (!josmTmpDir.exists() && !josmTmpDir.mkdirs()) {
893            Main.warn("Unable to create temp directory "+josmTmpDir);
894        }
895        return josmTmpDir;
896    }
897
898    /**
899     * Returns a simple human readable (hours, minutes, seconds) string for a given duration in milliseconds.
900     * @param elapsedTime The duration in milliseconds
901     * @return A human readable string for the given duration
902     * @throws IllegalArgumentException if elapsedTime is &lt; 0
903     * @since 6354
904     */
905    public static String getDurationString(long elapsedTime) throws IllegalArgumentException {
906        if (elapsedTime < 0) {
907            throw new IllegalArgumentException("elapsedTime must be >= 0");
908        }
909        // Is it less than 1 second ?
910        if (elapsedTime < MILLIS_OF_SECOND) {
911            return String.format("%d %s", elapsedTime, tr("ms"));
912        }
913        // Is it less than 1 minute ?
914        if (elapsedTime < MILLIS_OF_MINUTE) {
915            return String.format("%.1f %s", elapsedTime / (float) MILLIS_OF_SECOND, tr("s"));
916        }
917        // Is it less than 1 hour ?
918        if (elapsedTime < MILLIS_OF_HOUR) {
919            final long min = elapsedTime / MILLIS_OF_MINUTE;
920            return String.format("%d %s %d %s", min, tr("min"), (elapsedTime - min * MILLIS_OF_MINUTE) / MILLIS_OF_SECOND, tr("s"));
921        }
922        // Is it less than 1 day ?
923        if (elapsedTime < MILLIS_OF_DAY) {
924            final long hour = elapsedTime / MILLIS_OF_HOUR;
925            return String.format("%d %s %d %s", hour, tr("h"), (elapsedTime - hour * MILLIS_OF_HOUR) / MILLIS_OF_MINUTE, tr("min"));
926        }
927        long days = elapsedTime / MILLIS_OF_DAY;
928        return String.format("%d %s %d %s", days, trn("day", "days", days), (elapsedTime - days * MILLIS_OF_DAY) / MILLIS_OF_HOUR, tr("h"));
929    }
930
931    /**
932     * Returns a human readable representation of a list of positions.
933     * <p>
934     * For instance, {@code [1,5,2,6,7} yields "1-2,5-7
935     * @param positionList a list of positions
936     * @return a human readable representation
937     */
938    public static String getPositionListString(List<Integer> positionList)  {
939        Collections.sort(positionList);
940        final StringBuilder sb = new StringBuilder(32);
941        sb.append(positionList.get(0));
942        int cnt = 0;
943        int last = positionList.get(0);
944        for (int i = 1; i < positionList.size(); ++i) {
945            int cur = positionList.get(i);
946            if (cur == last + 1) {
947                ++cnt;
948            } else if (cnt == 0) {
949                sb.append(",").append(cur);
950            } else {
951                sb.append("-").append(last);
952                sb.append(",").append(cur);
953                cnt = 0;
954            }
955            last = cur;
956        }
957        if (cnt >= 1) {
958            sb.append("-").append(last);
959        }
960        return sb.toString();
961    }
962
963
964    /**
965     * Returns a list of capture groups if {@link Matcher#matches()}, or {@code null}.
966     * The first element (index 0) is the complete match.
967     * Further elements correspond to the parts in parentheses of the regular expression.
968     * @param m the matcher
969     * @return a list of capture groups if {@link Matcher#matches()}, or {@code null}.
970     */
971    public static List<String> getMatches(final Matcher m) {
972        if (m.matches()) {
973            List<String> result = new ArrayList<>(m.groupCount() + 1);
974            for (int i = 0; i <= m.groupCount(); i++) {
975                result.add(m.group(i));
976            }
977            return result;
978        } else {
979            return null;
980        }
981    }
982
983    /**
984     * Cast an object savely.
985     * @param <T> the target type
986     * @param o the object to cast
987     * @param klass the target class (same as T)
988     * @return null if <code>o</code> is null or the type <code>o</code> is not
989     *  a subclass of <code>klass</code>. The casted value otherwise.
990     */
991    @SuppressWarnings("unchecked")
992    public static <T> T cast(Object o, Class<T> klass) {
993        if (klass.isInstance(o)) {
994            return (T) o;
995        }
996        return null;
997    }
998
999    /**
1000     * Returns the root cause of a throwable object.
1001     * @param t The object to get root cause for
1002     * @return the root cause of {@code t}
1003     * @since 6639
1004     */
1005    public static Throwable getRootCause(Throwable t) {
1006        Throwable result = t;
1007        if (result != null) {
1008            Throwable cause = result.getCause();
1009            while (cause != null && cause != result) {
1010                result = cause;
1011                cause = result.getCause();
1012            }
1013        }
1014        return result;
1015    }
1016
1017    /**
1018     * Adds the given item at the end of a new copy of given array.
1019     * @param array The source array
1020     * @param item The item to add
1021     * @return An extended copy of {@code array} containing {@code item} as additional last element
1022     * @since 6717
1023     */
1024    public static <T> T[] addInArrayCopy(T[] array, T item) {
1025        T[] biggerCopy = Arrays.copyOf(array, array.length + 1);
1026        biggerCopy[array.length] = item;
1027        return biggerCopy;
1028    }
1029
1030    /**
1031     * If the string {@code s} is longer than {@code maxLength}, the string is cut and "..." is appended.
1032     */
1033    public static String shortenString(String s, int maxLength) {
1034        if (s != null && s.length() > maxLength) {
1035            return s.substring(0, maxLength - 3) + "...";
1036        } else {
1037            return s;
1038        }
1039    }
1040
1041    /**
1042     * Fixes URL with illegal characters in the query (and fragment) part by
1043     * percent encoding those characters.
1044     *
1045     * special characters like &amp; and # are not encoded
1046     *
1047     * @param url the URL that should be fixed
1048     * @return the repaired URL
1049     */
1050    public static String fixURLQuery(String url) {
1051        if (url.indexOf('?') == -1)
1052            return url;
1053
1054        String query = url.substring(url.indexOf('?') + 1);
1055
1056        StringBuilder sb = new StringBuilder(url.substring(0, url.indexOf('?') + 1));
1057
1058        for (int i=0; i<query.length(); i++) {
1059            String c = query.substring(i, i+1);
1060            if (URL_CHARS.contains(c)) {
1061                sb.append(c);
1062            } else {
1063                try {
1064                    sb.append(URLEncoder.encode(c, "UTF-8"));
1065                } catch (UnsupportedEncodingException ex) {
1066                    throw new RuntimeException(ex);
1067                }
1068            }
1069        }
1070        return sb.toString();
1071    }
1072
1073    /**
1074     * Determines if the given URL denotes a file on a local filesystem.
1075     * @param url The URL to test
1076     * @return {@code true} if the url points to a local file
1077     * @since 7356
1078     */
1079    public static boolean isLocalUrl(String url) {
1080        if (url.startsWith("http://") || url.startsWith("https://") || url.startsWith("resource://"))
1081            return false;
1082        return true;
1083    }
1084
1085    /**
1086     * Returns a pair containing the number of threads (n), and a thread pool (if n > 1) to perform
1087     * multi-thread computation in the context of the given preference key.
1088     * @param pref The preference key
1089     * @return a pair containing the number of threads (n), and a thread pool (if n > 1, null otherwise)
1090     * @since 7423
1091     */
1092    public static Pair<Integer, ExecutorService> newThreadPool(String pref) {
1093        int noThreads = Main.pref.getInteger(pref, Runtime.getRuntime().availableProcessors());
1094        ExecutorService pool = noThreads <= 1 ? null : Executors.newFixedThreadPool(noThreads);
1095        return new Pair<>(noThreads, pool);
1096    }
1097}