|
|
The Core Network module provide ProxySelector as well as utilities related to network connections.
Question (arch-overall): Describe the overall architecture. Answer:The Core Network module provide ProxySelector as well as utilities related to network connections.
ProxySelector
The role of a ProxySelector is to tell to the rest of Java which
proxy to use for a given URL. There's only one ProxySelector in a given
JVM. Most notably the ProxySelector is used by the URLConnection
classes and even the new HTTP client in JDK9 is using it, although it allows
more control over this than does the URLConnection classes.
Also, the Apache HttpClient is also using the default ProxySelector if you have instructed
it to use what is known in Apache HttpClient as SystemDefaultRoutePlanner.
This module provides an implementation of a ProxySelector which finds out which proxy to use by looking at preferences the user has stored. This is trivial for the case where the user has provided explicit proxy information. It is more complex for the case where the user has said "just use my system's proxy configuration" which is by the way the default in NetBeans. This requires us to go the underlying OS and try to figure out what the user's settings are. In many case case the user will not have explicit proxy setting in the OS either but will simply have "Automatically detect settings" or whatever. This makes it even more complex (see WPAD section below).
The ProxySelector is instantiated by the Startup module, but only if module Core also exists. Thus, for a minimal Platform application which only use the modules from the "Runtime Container", there will be no ProxySelector installed because module Core is not part of the Runtime Container. In this case, the standard ProxySelector in Java will then be used. This makes sense because a headless application will not have stored Preferences about proxy, etc, and will be much better off by just using the standard ProxySelector (which can be controlled by properties).
Module Core uses the Global Lookup to search for a ProxySelector, so you can register your own ProxySelector if you don't like the one provided by the Platform (i.e. this module). This will be somewhat difficult though, because in order to implement your own ProxySelector, you would need read access to the stored ProxySettings. This class is currently only exposed to friends.
Proxy Auto-Config (PAC)
Very often the proxy configuration on a corporate network is not given explictly. Instead it is given in a little JavaScript file which clients are supposed to download and execute in order to find out which proxy to use. This is known as Proxy Auto-Config (or PAC). This module provides a pluggable PAC evaluation environment based on available JavaScript engine installed in the JVM. Execution of the downloaded JavaScript code is sandboxed.
org.netbeans.core.network.proxy.pac.impl.ALLOWED_PAC_ENGINES - To further secure execution of downloaded scripts, it is possible to restrict the set of allowed ScriptEngines to evaluate the PAC scripts. Provide a branding of bundleorg.netbeans.core.network.proxy.pac.impl.Bundle
in your own application
and change the value of ALLOWED_PAC_ENGINES key.
The default is GraalVM:js,Graal.js,Nashorn - e.g. the engines
currently considered secure.
If you don't like the PAC evaluation environment provided
by this module then you can plug in your own by registering
your own PacScriptEvaluatorFactory class in the Global Lookup.
If you want to build your own PAC evaluation environment then you can
still make use of all the utility classes provided by this module.
Locating the PAC script (WPAD)
Normally, a Web Browser (in comparison) can locate the PAC script either explicitly, meaning the URL is directly available from the settings in the OS, or it can be located via WPAD This module currently only supports the case where URL is directly available from the settings. There's no support for WPAD.
Question (arch-usecases): Describe the main use cases of the new API. Who will use it under what circumstances? What kind of code would typically need to be written to use the module? Answer:
PacHelperMethods you may
take benefit from the PAC utility functions provided by {@link org.netbeans.core.network.proxy.pac.PacUtils}
and {@link org.netbeans.core.network.proxy.pac.datetime.PacUtilsDateTime},
as well as the more general ones provided by {@link org.netbeans.core.network.utils network utils package}.
org.netbeans.core.network.proxy.pac.PacHelperMethods
org.netbeans.core.network.utils.HostnameUtils
org.netbeans.core.network.utils.IpAddressUtils
org.netbeans.core.network.utils.LocalAddressUtils
org.netbeans.core.network.utils.SimpleObjCache
org.netbeans.core.network.proxy.pac.PacUtils
org.netbeans.core.network.proxy.pac.datetime.PacUtilsDateTime
Question (arch-time):
What are the time estimates of the work?
Answer:
XXX no answer for arch-time
Question (arch-quality): How will the quality of your code be tested and how are future regressions going to be prevented? Answer:XXX no answer for arch-quality
Question (arch-where): Where one can find sources for your module? Answer:
The sources for the module are in the Apache Git repositories or in the GitHub repositories.
These modules are required in project.xml:
XXX no answer for dep-non-nb
Question (dep-platform): On which platforms does your module run? Does it run in the same way on each? Answer:The module uses JNA to look up various information about the host. Currently there's support for Windows dektops, Mac OS X desktops, KDE desktops and Gnome desktops.
Question (dep-jre): Which version of JRE do you need (1.2, 1.3, 1.4, etc.)? Answer:Java 1.8 or later is required.
Question (dep-jrejdk): Do you require the JDK or is the JRE enough? Answer:Only JRE is needed.
XXX no answer for deploy-jar
Question (deploy-nbm): Can you deploy an NBM via the Update Center? Answer:Yes
Question (deploy-shared): Do you need to be installed in the shared location only, or in the user directory only, or can your module be installed anywhere? Answer:Can be installed anywhere
Question (deploy-packages): Are packages of your module made inaccessible by not declaring them public? Answer:XXX no answer for deploy-packages
Question (deploy-dependencies): What do other modules need to do to declare a dependency on this one, in addition to or instead of the normal module dependency declaration (e.g. tokens to require)? Answer:XXX no answer for deploy-dependencies
XXX no answer for compat-i18n
Question (compat-standards): Does the module implement or define any standards? Is the implementation exact or does it deviate somehow? Answer:The module implements the Proxy-Auto Config (PAC) specification as first specified by Netscape and then later amended by Microsoft. The PAC script is a small piece of JavaScript, typically downloaded from the network. The purpose of the PAC script is to determine which proxy to use for a given URL.
In particular the specification from Netscape was very vaque. This has led to various inconsistencies between how browsers (or other software) has implemented this. The implementation in this module aims to support just about every corner case and to be as compatible as possible with how the PAC script is interpreted by various browsers. Whenever the standard is ambigious, the implementation provided by the module deliberately interprets the specification in the widest possible sense. More information in the Javadoc for {@link org.netbeans.core.network.proxy.pac.impl.NbPacScriptEvaluator}.
Question (compat-version): Can your module coexist with earlier and future versions of itself? Can you correctly read all old settings? Will future versions be able to read your current settings? Can you read or politely ignore settings stored by a future version? Answer:XXX no answer for compat-version
Question (compat-deprecation): How the introduction of your project influences functionality provided by previous version of the product? Answer:XXX no answer for compat-deprecation
java.io.File directly?
Answer:
No
Question (resources-layer): Does your module provide own layer? Does it create any files or folders in it? What it is trying to communicate by that and with which components? Answer:XXX no answer for resources-layer
Question (resources-read): Does your module read any resources from layers? For what purpose? Answer:XXX no answer for resources-read
Question (resources-mask): Does your module mask/hide/override any resources provided by other modules in their layers? Answer:No
Question (resources-preferences): Does your module uses preferences via Preferences API? Does your module use NbPreferences or or regular JDK Preferences ? Does it read, write or both ? Does it share preferences with other modules ? If so, then why ? Answer:
The module reads Proxy Preferences using NbPreferences.
org.openide.util.Lookup
or any similar technology to find any components to communicate with? Which ones?
Answer:
XXX no answer for lookup-lookup
Question (lookup-register): Do you register anything into lookup for other code to find? Answer:
The, this module registers a NetBeans ProxySelector into
the Global Lookup. It also registers a PacScriptEvaluatorFactory
which is used by the NetBeans ProxySelector itself.
No
System.getProperty) property?
On a similar note, is there something interesting that you
pass to java.util.logging.Logger? Or do you observe
what others log?
Answer:
No
Question (exec-component): Is execution of your code influenced by any (string) property of any of your components? Answer:No
Question (exec-ant-tasks): Do you define or register any ant tasks that other can use? Answer:No
Question (exec-classloader): Does your code create its own class loader(s)? Answer:No
Question (exec-reflection): Does your code use Java Reflection to execute other code? Answer:
For testing only a dirty hack is used in our FakeDns class.
This installs itself as a preferred name service in Java. This is done
via reflection. It also uses proprietary sun.* package.
However, it is only used for unit testing.
No.
Question (exec-process): Do you execute an external process from your module? How do you ensure that the result is the same on different platforms? Do you parse output? Do you depend on result code? Answer:XXX no answer for exec-process
Question (exec-introspection): Does your module use any kind of runtime type information (instanceof,
work with java.lang.Class, etc.)?
Answer:
Yes: Distinguishing between IPv4 and IPv6 instances is by
doing (example) : inetAddress instanceof Inet6Address.
This seems to be the generally accepted way of doing it.
Documented in Javadoc where relevant.
Question (security-policy): Does your functionality require modifications to the standard policy file? Answer:No
Question (security-grant): Does your code grant additional rights to some other code? Answer:XXX no answer for security-grant
Not applicable.
Question (format-dnd): Which protocols (if any) does your code understand during Drag & Drop? Answer:Not applicable.
Question (format-clipboard): Which data flavors (if any) does your code read from or insert to the clipboard (by access to clipboard on means calling methods onjava.awt.datatransfer.Transferable?
Answer:
Not applicable.
Yes. The initialization of the ProxySelector (i.e. calling its constructor) is done as part of the platform startup process in module Startup. Moreso, it is done on the platform main thread. In other words: The constructor needs to be quick as it influences platform startup time. At the moment this constructor is fairly lazy. For example it postpones download of PAC file. However, the constructor can be further improved in terms of startup speed.
Question (perf-exit): Does your module run any code on exit? Answer:No
Question (perf-scale): Which external criteria influence the performance of your program (size of file in editor, number of files in menu, in source directory, etc.) and how well your code scales? Answer:XXX no answer for perf-scale
Question (perf-limit): Are there any hard-coded or practical limits in the number or size of elements your code can handle? Answer:No
Question (perf-mem): How much memory does your component consume? Estimate with a relation to the number of windows, etc. Answer:XXX no answer for perf-mem
Question (perf-wakeup): Does any piece of your code wake up periodically and do something even when the system is otherwise idle (no user interaction)? Answer:No
Question (perf-progress): Does your module execute any long-running tasks? Answer:Yes. It executes tasks such as downloading PAC script from network. This is done in a RequestProcessor. It also provides utility methods for doing name lookup with a timeout.
Question (perf-huge_dialogs): Does your module contain any dialogs or wizards with a large number of GUI controls such as combo boxes, lists, trees, or text areas? Answer:No
Question (perf-menus): Does your module use dynamically updated context menus, or context-sensitive actions with complicated and slow enablement logic? Answer:Not applicable. There's no GUI in this module.
Question (perf-spi): How the performance of the plugged in code will be enforced? Answer:XXX no answer for perf-spi